llm-cli-gateway 1.4.0 → 1.5.13

package/dist/doctor.js

@@ -0,0 +1,280 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir, platform, arch, release } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadAuthConfig } from "./auth.js";
+import { createEndpointExposureReport, redactDiagnosticUrl, } from "./endpoint-exposure.js";
+import { listProviderRuntimeStatuses, } from "./provider-status.js";
+import { CLAUDE_MCP_SERVER_NAMES } from "./claude-mcp-config.js";
+/**
+ * Probe ~/.vibe/config.toml to see whether session_logging is enabled. Vibe
+ * persists session logs (which sessionId/--continue depends on) only when
+ * `[session_logging] enabled = true` is set. The probe is read-only: the
+ * gateway never mutates this file.
+ */
+export function checkVibeSessionLogging(home = homedir()) {
+    const configPath = join(home, ".vibe", "config.toml");
+    if (!existsSync(configPath)) {
+        return {
+            config_path: configPath,
+            config_present: false,
+            session_logging_enabled: false,
+            note: "~/.vibe/config.toml not found. Run `vibe config set session_logging.enabled true` or create the file with a [session_logging]\\nenabled = true block.",
+        };
+    }
+    try {
+        const text = readFileSync(configPath, "utf8");
+        const enabled = parseVibeSessionLoggingEnabled(text);
+        if (enabled) {
+            return {
+                config_path: configPath,
+                config_present: true,
+                session_logging_enabled: true,
+                note: "session_logging.enabled is true; --continue/--resume will work for mistral_request.",
+            };
+        }
+        return {
+            config_path: configPath,
+            config_present: true,
+            session_logging_enabled: false,
+            note: "[session_logging] enabled = false (or missing). Run `vibe config set session_logging.enabled true` or edit ~/.vibe/config.toml so mistral_request --resume / --continue can persist sessions.",
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            config_path: configPath,
+            config_present: true,
+            session_logging_enabled: false,
+            note: `Could not parse ~/.vibe/config.toml: ${message}. Verify the file is valid TOML.`,
+        };
+    }
+}
+/**
+ * Tiny TOML probe focused on `[session_logging] enabled = true`. Avoids pulling
+ * in the full `toml` parser when only one boolean is needed.
+ */
+function parseVibeSessionLoggingEnabled(text) {
+    const lines = text.split(/\r?\n/);
+    let inSection = false;
+    for (let raw of lines) {
+        const line = raw.replace(/#.*$/, "").trim();
+        if (!line)
+            continue;
+        const sectionMatch = line.match(/^\[\s*([A-Za-z0-9_.-]+)\s*\]$/);
+        if (sectionMatch) {
+            inSection = sectionMatch[1] === "session_logging";
+            continue;
+        }
+        if (inSection) {
+            const kv = line.match(/^enabled\s*=\s*(.+)$/);
+            if (kv) {
+                const value = kv[1].trim().toLowerCase();
+                return value === "true";
+            }
+        }
+        else {
+            // Allow dotted form: session_logging.enabled = true
+            const dotted = line.match(/^session_logging\.enabled\s*=\s*(.+)$/);
+            if (dotted) {
+                const value = dotted[1].trim().toLowerCase();
+                return value === "true";
+            }
+        }
+    }
+    return false;
+}
+/**
+ * U27: Probe Gemini's project/user config locations.
+ *
+ * - `./GEMINI.md` (gateway cwd) and `~/.gemini/GEMINI.md` are documented
+ *   "context" surfaces. Missing both means Gemini has no project-specific
+ *   guidance.
+ * - `~/.gemini/settings.json` defines registered MCP servers (`mcpServers`
+ *   block). The gateway tracks its own whitelist (`CLAUDE_MCP_SERVER_NAMES`)
+ *   and surfaces a reconciliation warning for each whitelisted server not
+ *   present in settings.json so callers don't ship requests for unregistered
+ *   servers.
+ */
+export function checkGeminiConfig(cwd = process.cwd(), home = homedir(), whitelist = CLAUDE_MCP_SERVER_NAMES) {
+    const projectGeminiMd = join(cwd, "GEMINI.md");
+    const userGeminiMd = join(home, ".gemini", "GEMINI.md");
+    const settingsPath = join(home, ".gemini", "settings.json");
+    const projectGeminiMdPresent = existsSync(projectGeminiMd);
+    const userGeminiMdPresent = existsSync(userGeminiMd);
+    const settingsPresent = existsSync(settingsPath);
+    let mcpServersRegistered = [];
+    if (settingsPresent) {
+        try {
+            const raw = readFileSync(settingsPath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed.mcpServers === "object" && parsed.mcpServers) {
+                mcpServersRegistered = Object.keys(parsed.mcpServers);
+            }
+        }
+        catch {
+            // Best-effort: leave list empty so the next_action surfaces the gap.
+        }
+    }
+    const missingFromSettings = whitelist.filter(name => !mcpServersRegistered.includes(name));
+    const nextActions = [];
+    if (!projectGeminiMdPresent && !userGeminiMdPresent) {
+        nextActions.push(`Create ${projectGeminiMd} to give Gemini project-specific context (or ${userGeminiMd} for a user-wide default).`);
+    }
+    if (!settingsPresent) {
+        nextActions.push(`Create ${settingsPath} to register MCP servers (mcpServers block). Run \`gemini mcp add <name>\` for each gateway-whitelisted server.`);
+    }
+    for (const name of missingFromSettings) {
+        nextActions.push(`MCP server \`${name}\` is whitelisted by the gateway but not registered in ${settingsPath}. Run \`gemini mcp add ${name}\` to register it.`);
+    }
+    return {
+        project_gemini_md_present: projectGeminiMdPresent,
+        project_gemini_md_path: projectGeminiMd,
+        user_gemini_md_present: userGeminiMdPresent,
+        user_gemini_md_path: userGeminiMd,
+        settings_json_present: settingsPresent,
+        settings_json_path: settingsPath,
+        mcp_servers_registered: mcpServersRegistered,
+        mcp_reconciliation: {
+            whitelisted: [...whitelist],
+            missing_from_settings: missingFromSettings,
+        },
+        next_actions: nextActions,
+    };
+}
+function packageVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [join(here, "..", "package.json"), join(here, "..", "..", "package.json")];
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(readFileSync(candidate, "utf8"));
+            return parsed.version || "unknown";
+        }
+        catch {
+            // Try next candidate.
+        }
+    }
+    return "unknown";
+}
+function clientConfigStatus(home = homedir()) {
+    return {
+        claude_desktop_config_present: existsSync(join(home, "Library/Application Support/Claude/claude_desktop_config.json")) ||
+            existsSync(join(home, ".config", "Claude", "claude_desktop_config.json")),
+        codex_config_present: existsSync(join(home, ".codex", "config.toml")),
+        gemini_settings_present: existsSync(join(home, ".gemini", "settings.json")) ||
+            existsSync(join(home, ".config", "gemini", "settings.json")),
+        gemini_config: checkGeminiConfig(process.cwd(), home),
+        vibe_session_logging: checkVibeSessionLogging(home),
+    };
+}
+function defaultTransport(env) {
+    if (env.LLM_GATEWAY_TRANSPORT === "http" || env.MCP_TRANSPORT === "http")
+        return "http";
+    return "stdio";
+}
+export function createDoctorReport(env = process.env) {
+    const auth = loadAuthConfig(env);
+    const transport = defaultTransport(env);
+    const rawPublicUrl = env.LLM_GATEWAY_PUBLIC_URL || null;
+    const publicUrl = redactDiagnosticUrl(rawPublicUrl);
+    const endpointExposure = createEndpointExposureReport(env, publicUrl);
+    const providerStatuses = listProviderRuntimeStatuses();
+    const report = {
+        schema_version: "1.0",
+        ok: true,
+        generated_at: new Date().toISOString(),
+        system: {
+            os: platform(),
+            arch: arch(),
+            release: release(),
+            node_version: process.version,
+        },
+        gateway: {
+            name: "llm-cli-gateway",
+            version: packageVersion(),
+        },
+        transport: {
+            default: transport,
+            http: {
+                enabled: transport === "http",
+                host: env.LLM_GATEWAY_HTTP_HOST || "127.0.0.1",
+                port: Number(env.LLM_GATEWAY_HTTP_PORT || 3333),
+                path: env.LLM_GATEWAY_HTTP_PATH || "/mcp",
+                public_url_configured: Boolean(publicUrl),
+                public_url: publicUrl,
+            },
+        },
+        auth: {
+            required: auth.required,
+            token_configured: auth.tokenConfigured,
+            source: auth.source,
+        },
+        providers: {
+            claude: doctorProviderStatus(providerStatuses.claude),
+            codex: doctorProviderStatus(providerStatuses.codex),
+            gemini: doctorProviderStatus(providerStatuses.gemini),
+            grok: doctorProviderStatus(providerStatuses.grok),
+            mistral: doctorProviderStatus(providerStatuses.mistral),
+        },
+        endpoint_exposure: endpointExposure,
+        client_config: clientConfigStatus(),
+        next_actions: [],
+    };
+    if (transport === "http" && auth.required && !auth.tokenConfigured) {
+        report.ok = false;
+        report.next_actions.push("Set LLM_GATEWAY_AUTH_TOKEN before starting HTTP transport.");
+    }
+    report.next_actions.push(...endpointExposure.next_actions);
+    for (const [name, provider] of Object.entries(report.providers)) {
+        if (!provider.cli_available) {
+            report.next_actions.push(provider.install_guidance.summary);
+        }
+        else if (provider.login_status !== "authenticated") {
+            report.next_actions.push(`${name}: ${provider.login_guidance.summary}`);
+        }
+    }
+    // Mistral-specific: surface the session_logging toggle BEFORE a --continue/--resume
+    // request fails opaquely. The check is read-only; the gateway never mutates the file.
+    const vibeStatus = report.client_config.vibe_session_logging;
+    if (report.providers.mistral.cli_available && !vibeStatus.session_logging_enabled) {
+        report.next_actions.push(`mistral: ${vibeStatus.note}`);
+    }
+    // U27: surface Gemini config gaps (missing GEMINI.md, missing settings.json,
+    // MCP-server whitelist drift) only when Gemini CLI is actually installed.
+    if (report.providers.gemini.cli_available) {
+        for (const action of report.client_config.gemini_config.next_actions) {
+            report.next_actions.push(`gemini: ${action}`);
+        }
+    }
+    if (report.next_actions.length === 0) {
+        report.next_actions.push("Run a client setup guide and verify with doctor --json after each step.");
+    }
+    return report;
+}
+export function printDoctorJson() {
+    process.stdout.write(`${JSON.stringify(createDoctorReport(), null, 2)}\n`);
+}
+function doctorProviderStatus(provider) {
+    return {
+        cli_available: provider.installed,
+        version: provider.version,
+        login_status: provider.loginStatus,
+        version_command: provider.versionCommand,
+        login_check: {
+            method: provider.loginCheck.method,
+            command: provider.loginCheck.command,
+            credential_store: provider.loginCheck.credentialStore,
+            detail: provider.loginCheck.detail,
+        },
+        install_guidance: {
+            summary: provider.guidance.install.summary,
+            commands: provider.guidance.install.commands,
+            documentation_url: provider.guidance.install.documentationUrl,
+        },
+        login_guidance: {
+            summary: provider.guidance.login.summary,
+            commands: provider.guidance.login.commands,
+            credential_handling: provider.guidance.login.credentialHandling,
+        },
+    };
+}

package/dist/endpoint-exposure.d.ts

@@ -0,0 +1,22 @@
+export type EndpointExposureMode = "local_only" | "lan" | "tunnel" | "byo_reverse_proxy" | "misconfigured";
+export type EndpointReachability = "not_checked" | "reachable" | "unreachable";
+export interface EndpointExposureReport {
+    mode: EndpointExposureMode;
+    local_url: string;
+    public_url_configured: boolean;
+    public_url: string | null;
+    https_required_for_web: boolean;
+    https_configured: boolean;
+    web_clients_supported: boolean;
+    tunnel_provider: string | null;
+    reachable_from_web: EndpointReachability;
+    verification: {
+        method: "not_checked" | "http_head";
+        checked_url: string | null;
+        status_code: number | null;
+        error: string | null;
+    };
+    next_actions: string[];
+}
+export declare function createEndpointExposureReport(env: NodeJS.ProcessEnv, redactedPublicUrl: string | null): EndpointExposureReport;
+export declare function redactDiagnosticUrl(rawUrl: string | null): string | null;

package/dist/endpoint-exposure.js

@@ -0,0 +1,231 @@
+import { spawnSync } from "node:child_process";
+const TUNNEL_HOST_PATTERNS = [
+    /cloudflare/i,
+    /trycloudflare\.com$/i,
+    /ngrok(?:-free)?\.app$/i,
+    /ngrok\.io$/i,
+    /ts\.net$/i,
+    /tailscale/i,
+];
+export function createEndpointExposureReport(env, redactedPublicUrl) {
+    const host = env.LLM_GATEWAY_HTTP_HOST || "127.0.0.1";
+    const port = Number(env.LLM_GATEWAY_HTTP_PORT || 3333);
+    const path = env.LLM_GATEWAY_HTTP_PATH || "/mcp";
+    const localHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+    const localUrl = `http://${localHost}:${port}${path}`;
+    const rawPublicUrl = env.LLM_GATEWAY_PUBLIC_URL || "";
+    const tunnelProvider = env.LLM_GATEWAY_TUNNEL_PROVIDER || inferTunnelProvider(rawPublicUrl);
+    const httpsConfigured = rawPublicUrl.startsWith("https://");
+    const publicConfigured = Boolean(redactedPublicUrl);
+    const mode = classifyEndpointMode({ host, rawPublicUrl, tunnelProvider, httpsConfigured });
+    const verification = maybeVerifyEndpoint(env, rawPublicUrl, mode);
+    const webClientsSupported = publicConfigured &&
+        httpsConfigured &&
+        mode !== "local_only" &&
+        mode !== "lan" &&
+        verification.reachable_from_web === "reachable";
+    const nextActions = [];
+    if (!publicConfigured) {
+        nextActions.push("Keep using local stdio/CLI clients, or configure an HTTPS tunnel before web-client setup.");
+    }
+    else if (mode === "local_only" || mode === "lan") {
+        nextActions.push("Set LLM_GATEWAY_PUBLIC_URL to a public HTTPS tunnel or reverse-proxy URL, not localhost or a LAN address.");
+    }
+    else if (!httpsConfigured) {
+        nextActions.push("Use an HTTPS public URL before configuring ChatGPT, Claude web, or Grok web connectors.");
+    }
+    if (publicConfigured && mode !== "local_only" && mode !== "lan") {
+        if (verification.method === "not_checked") {
+            nextActions.push("Set LLM_GATEWAY_VERIFY_PUBLIC_URL=1 to have doctor check public endpoint reachability.");
+        }
+        else if (verification.reachable_from_web === "unreachable") {
+            nextActions.push("Fix tunnel/proxy routing until the public MCP URL is reachable, then rerun doctor --json.");
+        }
+    }
+    return {
+        mode,
+        local_url: localUrl,
+        public_url_configured: publicConfigured,
+        public_url: redactedPublicUrl,
+        https_required_for_web: true,
+        https_configured: httpsConfigured,
+        web_clients_supported: webClientsSupported,
+        tunnel_provider: tunnelProvider || null,
+        reachable_from_web: verification.reachable_from_web,
+        verification: {
+            method: verification.method,
+            checked_url: verification.checked_url ? redactDiagnosticUrl(verification.checked_url) : null,
+            status_code: verification.status_code,
+            error: verification.error,
+        },
+        next_actions: nextActions,
+    };
+}
+export function redactDiagnosticUrl(rawUrl) {
+    if (!rawUrl)
+        return null;
+    const sensitiveKeyPattern = /auth|bearer|token|secret|credential|password|authorization|signature|api[_-]?key|access[_-]?key|jwt|cookie|session/i;
+    const redactSensitivePairs = (value) => value.replace(new RegExp(`((${sensitiveKeyPattern.source})=)[^&\\s#]+`, "gi"), "$1<redacted>");
+    try {
+        const url = new URL(rawUrl);
+        if (url.username)
+            url.username = "<redacted>";
+        if (url.password)
+            url.password = "<redacted>";
+        for (const key of Array.from(url.searchParams.keys())) {
+            if (sensitiveKeyPattern.test(key)) {
+                url.searchParams.set(key, "<redacted>");
+            }
+        }
+        url.hash = redactSensitivePairs(url.hash);
+        return url.toString().replace(/%3Credacted%3E/gi, "<redacted>");
+    }
+    catch {
+        return redactSensitivePairs(rawUrl.replace(/(https?:\/\/)[^/@]+@/gi, "$1<redacted>@"));
+    }
+}
+function classifyEndpointMode(input) {
+    if (!input.rawPublicUrl) {
+        if (input.host === "0.0.0.0" || input.host === "::" || isLanHost(input.host))
+            return "lan";
+        return "local_only";
+    }
+    const publicHost = publicUrlHost(input.rawPublicUrl);
+    if (!publicHost)
+        return "misconfigured";
+    if (isLoopbackHost(publicHost))
+        return "local_only";
+    if (isLanHost(publicHost))
+        return "lan";
+    if (!input.httpsConfigured)
+        return "misconfigured";
+    if (input.tunnelProvider)
+        return "tunnel";
+    return "byo_reverse_proxy";
+}
+function inferTunnelProvider(rawUrl) {
+    if (!rawUrl)
+        return "";
+    try {
+        const host = new URL(rawUrl).hostname;
+        if (TUNNEL_HOST_PATTERNS.some(pattern => pattern.test(host)))
+            return host;
+    }
+    catch {
+        // Treat unparsable URLs as not classified.
+    }
+    return "";
+}
+function isLanHost(host) {
+    const normalized = normalizeHost(host);
+    const mappedIpv4 = ipv4FromMappedIpv6(normalized);
+    if (mappedIpv4)
+        return isLanHost(mappedIpv4);
+    return (/^10\./.test(normalized) ||
+        /^192\.168\./.test(normalized) ||
+        /^172\.(1[6-9]|2\d|3[0-1])\./.test(normalized) ||
+        /^f[cd][0-9a-f]{2}:/i.test(normalized) ||
+        /^fe80:/i.test(normalized));
+}
+function isLoopbackHost(host) {
+    const normalized = normalizeHost(host);
+    const mappedIpv4 = ipv4FromMappedIpv6(normalized);
+    if (mappedIpv4)
+        return isLoopbackHost(mappedIpv4);
+    return (normalized === "localhost" ||
+        normalized === "0.0.0.0" ||
+        normalized === "::" ||
+        normalized === "::1" ||
+        /^127\./.test(normalized));
+}
+function publicUrlHost(rawUrl) {
+    try {
+        return normalizeHost(new URL(rawUrl).hostname);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeHost(host) {
+    return host.toLowerCase().replace(/^\[|\]$/g, "");
+}
+function ipv4FromMappedIpv6(host) {
+    const dotted = host.match(/^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i);
+    if (dotted)
+        return dotted[1];
+    const hex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+    if (!hex)
+        return null;
+    const high = Number.parseInt(hex[1], 16);
+    const low = Number.parseInt(hex[2], 16);
+    if (!Number.isFinite(high) || !Number.isFinite(low))
+        return null;
+    return `${(high >> 8) & 255}.${high & 255}.${(low >> 8) & 255}.${low & 255}`;
+}
+function maybeVerifyEndpoint(env, rawPublicUrl, mode) {
+    if (!rawPublicUrl || env.LLM_GATEWAY_VERIFY_PUBLIC_URL !== "1") {
+        return {
+            method: "not_checked",
+            checked_url: rawPublicUrl || null,
+            status_code: null,
+            error: null,
+            reachable_from_web: "not_checked",
+        };
+    }
+    if (mode === "local_only" || mode === "lan") {
+        return {
+            method: "not_checked",
+            checked_url: rawPublicUrl,
+            status_code: null,
+            error: "Public URL points to localhost or a private LAN address.",
+            reachable_from_web: "unreachable",
+        };
+    }
+    const result = verifyEndpointSync(rawPublicUrl, 3_000);
+    return {
+        method: "http_head",
+        checked_url: rawPublicUrl,
+        status_code: result.statusCode,
+        error: result.error,
+        reachable_from_web: result.ok ? "reachable" : "unreachable",
+    };
+}
+function verifyEndpointSync(url, timeoutMs) {
+    const script = `
+    const { request: http } = require("node:http");
+    const { request: https } = require("node:https");
+    const target = new URL(process.argv[1]);
+    const timeout = Number(process.argv[2]);
+    const requester = target.protocol === "https:" ? https : http;
+    const req = requester(target, { method: "HEAD", timeout, headers: { accept: "application/json, text/event-stream" } }, res => {
+      res.resume();
+      const statusCode = res.statusCode || 0;
+      const endpointFound = statusCode < 500 && statusCode !== 404;
+      console.log(JSON.stringify({ ok: endpointFound, statusCode: res.statusCode, error: null }));
+    });
+    req.on("timeout", () => {
+      req.destroy(new Error("Endpoint verification timed out."));
+    });
+    req.on("error", err => {
+      console.log(JSON.stringify({ ok: false, statusCode: null, error: err.message }));
+    });
+    req.end();
+  `;
+    const result = spawnSync(process.execPath, ["-e", script, url, String(timeoutMs)], {
+        encoding: "utf8",
+        timeout: timeoutMs + 1_000,
+    });
+    if (result.error) {
+        return {
+            ok: false,
+            statusCode: null,
+            error: result.error.message,
+        };
+    }
+    try {
+        return JSON.parse(result.stdout.trim());
+    }
+    catch {
+        return { ok: false, statusCode: null, error: "Endpoint verification failed." };
+    }
+}

package/dist/entrypoint-url.d.ts

@@ -0,0 +1 @@
+export declare function entrypointFileURL(path: string | undefined): string;

package/dist/entrypoint-url.js

@@ -0,0 +1,5 @@
+import { realpathSync } from "fs";
+import { pathToFileURL } from "url";
+export function entrypointFileURL(path) {
+    return path ? pathToFileURL(realpathSync(path)).href : "";
+}

package/dist/executor.d.ts

@@ -1,10 +1,12 @@
-import { ChildProcess } from "child_process";
+import { ChildProcess, type SpawnOptions } from "child_process";
 import type { Logger } from "./logger.js";
 export interface ExecuteOptions {
     timeout?: number;
     idleTimeout?: number;
     cwd?: string;
     logger?: Logger;
+    /** Extra environment variables to inject; merged after PATH. */
+    env?: NodeJS.ProcessEnv;
 }
 export interface ExecuteResult {
     stdout: string;
@@ -12,6 +14,7 @@ export interface ExecuteResult {
     code: number;
 }
 export declare function getExtendedPath(): string;
+export declare function shouldDetachProviderProcess(platform?: NodeJS.Platform): boolean;
 export declare function registerProcessGroup(pid: number): void;
 export declare function unregisterProcessGroup(pid: number): void;
 /**
@@ -27,4 +30,9 @@ export declare function killAllProcessGroups(): Promise<void>;
  * if the group kill fails (e.g., pid not yet assigned).
  */
 export declare function killProcessGroup(proc: ChildProcess, signal: NodeJS.Signals): boolean;
+export declare function spawnCliProcess(command: string, args: string[], options: {
+    cwd?: string;
+    env: NodeJS.ProcessEnv;
+    stdio: SpawnOptions["stdio"];
+}): ChildProcess;
 export declare function executeCli(command: string, args: string[], options?: ExecuteOptions): Promise<ExecuteResult>;

package/dist/executor.js

@@ -1,4 +1,4 @@
-import { spawn } from "child_process";
+import { spawn, spawnSync } from "child_process";
 import { homedir } from "os";
 import { join, dirname } from "path";
 import { readdirSync, existsSync } from "fs";
@@ -55,6 +55,12 @@ export function getExtendedPath() {
 }
 /** Registry of active detached process groups for shutdown cleanup. */
 const activeProcessGroups = new Set();
+export function shouldDetachProviderProcess(platform = process.platform) {
+    // On Windows, detached console children can flash visible cmd/conhost windows
+    // when provider CLIs are native console apps or .cmd shims. Keep them in the
+    // gateway process tree and rely on hidden-window spawn plus taskkill cleanup.
+    return platform !== "win32";
+}
 export function registerProcessGroup(pid) {
     activeProcessGroups.add(pid);
 }
@@ -72,21 +78,31 @@ export function killAllProcessGroups() {
     if (activeProcessGroups.size === 0)
         return Promise.resolve();
     for (const pid of activeProcessGroups) {
-        try {
-            process.kill(-pid, "SIGTERM");
+        if (process.platform === "win32") {
+            killWindowsProcessTree(pid);
         }
-        catch {
-            /* ESRCH ok */
+        else {
+            try {
+                process.kill(-pid, "SIGTERM");
+            }
+            catch {
+                /* ESRCH ok */
+            }
         }
     }
     return new Promise(resolve => {
         setTimeout(() => {
             for (const pid of activeProcessGroups) {
-                try {
-                    process.kill(-pid, "SIGKILL");
+                if (process.platform === "win32") {
+                    killWindowsProcessTree(pid);
                 }
-                catch {
-                    /* ESRCH ok */
+                else {
+                    try {
+                        process.kill(-pid, "SIGKILL");
+                    }
+                    catch {
+                        /* ESRCH ok */
+                    }
                 }
             }
             activeProcessGroups.clear();
@@ -100,6 +116,9 @@ export function killAllProcessGroups() {
  */
 export function killProcessGroup(proc, signal) {
     if (proc.pid) {
+        if (process.platform === "win32") {
+            return killWindowsProcessTree(proc.pid);
+        }
         try {
             process.kill(-proc.pid, signal);
             return true;
@@ -124,21 +143,37 @@ export function killProcessGroup(proc, signal) {
         return false;
     }
 }
+function killWindowsProcessTree(pid) {
+    const result = spawnSync("taskkill.exe", ["/PID", String(pid), "/T", "/F"], {
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    return result.status === 0;
+}
+export function spawnCliProcess(command, args, options) {
+    const detached = shouldDetachProviderProcess();
+    const proc = spawn(command, args, {
+        cwd: options.cwd,
+        detached,
+        windowsHide: true,
+        stdio: options.stdio,
+        env: options.env,
+    });
+    if (proc.pid)
+        registerProcessGroup(proc.pid);
+    proc.unref();
+    return proc;
+}
 export async function executeCli(command, args, options = {}) {
-    const { timeout, idleTimeout, cwd } = options;
+    const { timeout, idleTimeout, cwd, env: extraEnv } = options;
     const extendedPath = getExtendedPath();
     const circuitBreaker = getCircuitBreaker(command);
     const runOnce = () => new Promise((resolve, reject) => {
-        const proc = spawn(command, args, {
+        const proc = spawnCliProcess(command, args, {
             cwd,
-            detached: true,
             stdio: ["ignore", "pipe", "pipe"],
-            env: { ...process.env, PATH: extendedPath },
+            env: { ...process.env, PATH: extendedPath, ...(extraEnv ?? {}) },
         });
-        if (proc.pid)
-            registerProcessGroup(proc.pid);
-        // Prevent detached process from keeping parent alive when not needed
-        proc.unref();
         let stdout = "";
         let stderr = "";
         let timedOut = false;