mcp-castor 2026.3.0

package/src/wsl_env.js

@@ -0,0 +1,171 @@
+/**
+ * src/wsl_env.js — Leaf module: stateless WSL environment resolvers.
+ *
+ * Extracted from platform.js via dependency inversion so that config.js can
+ * import winHomeWsl() WITHOUT importing platform.js. This breaks the
+ * config.js <-> platform.js import cycle that produced a TDZ ReferenceError
+ * on Linux CI: when platform.js was the entry, its `_wslUser` cache (a
+ * module-level `let`) was still in the temporal dead zone while config.js's
+ * QWEN_STATE_DIR IIFE called winHomeWsl() at module-eval time.
+ *
+ * This module is a LEAF: it imports only node builtins and the leaf env.js.
+ * It carries the WSL user/home probe cache and the test seams. The
+ * Windows<->POSIX path translators remain in wsl_bridge.js (re-exported by
+ * platform.js) and are NOT reimplemented here.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import { execFileSync } from "node:child_process";
+import { IS_WINDOWS } from "./env.js";
+
+// ---------------------------------------------------------------------------
+// WSL distro / user / home
+// ---------------------------------------------------------------------------
+
+/** WSL distro name. Env QWEN_WSL_DISTRO; default "Ubuntu". */
+export function wslDistro() {
+  return process.env.QWEN_WSL_DISTRO || "Ubuntu";
+}
+
+let _wslUser = null;
+let _wslHome = null;
+let _wslUserProbeOk = null; // null = unknown, true = probe succeeded, false = probe failed
+
+function _probeWslUser() {
+  if (!IS_WINDOWS) {
+    // Already inside WSL/Linux: the current user IS the WSL user.
+    return process.env.USER || process.env.LOGNAME || "root";
+  }
+  try {
+    const out = execFileSync("wsl.exe", ["-d", wslDistro(), "whoami"], {
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const u = out.toString().trim();
+    return u || "root";
+  } catch {
+    // WSL unavailable / probe failed: signal failure (null) so the caller
+    // can fall back to root//root without throwing.
+    process.stderr.write(`[wsl_env] whoami probe failed; fabricating root identity.\n`);
+    return null;
+  }
+}
+
+// Test seam: lets offline tests inject a fake whoami probe (mirrors the
+// setWslRunner seam in server_lifecycle.js). Pass null to restore the real
+// probe. The real probe never throws (it returns null on failure).
+let _wslUserProbe = _probeWslUser;
+export function setWslUserProbe(fn) {
+  _wslUserProbe = typeof fn === "function" ? fn : _probeWslUser;
+}
+
+/** Clear the cached WSL user/home so the next call re-probes. Test-only. */
+export function _resetWslUserCache() {
+  _wslUser = null;
+  _wslHome = null;
+  _wslUserProbeOk = null;
+}
+
+/** WSL user name. Env QWEN_WSL_USER; otherwise probed once via whoami.
+ *  Never throws: any probe failure falls back to "root". */
+export function wslUser() {
+  if (process.env.QWEN_WSL_USER) return process.env.QWEN_WSL_USER;
+  if (_wslUser) return _wslUser;
+  let u;
+  let ok = true;
+  try {
+    u = _wslUserProbe();
+  } catch {
+    u = null;
+    ok = false;
+  }
+  _wslUserProbeOk = ok;
+  _wslUser = u || "root";
+  return _wslUser;
+}
+
+/** WSL home directory. Env QWEN_WSL_HOME; otherwise /home/<wslUser>.
+ *  When the whoami probe FAILED (WSL unavailable) it falls back to /root. */
+export function wslHome() {
+  if (process.env.QWEN_WSL_HOME) return process.env.QWEN_WSL_HOME;
+  if (_wslHome) return _wslHome;
+  if (_wslUserProbeOk === false) {
+    _wslHome = "/root";
+    return _wslHome;
+  }
+  _wslHome = `/home/${wslUser()}`;
+  return _wslHome;
+}
+
+/**
+ * The Windows user home as seen from WITHIN WSL (e.g. /mnt/c/Users/<user>),
+ * used to share the .qwen state dir between the Windows MCP server and the
+ * WSL engine. Env QWEN_WIN_HOME_WSL overrides. When unset, derived from
+ * QWEN_WIN_HOME if it is a Windows path (C:\Users\X -> /mnt/c/Users/X);
+ * when running inside WSL, auto-probes /mnt/c/Users/<user>; otherwise returns
+ * "" so callers fall back to the WSL user's own home.
+ *
+ * NOTE: the fs.existsSync probe below requires the `fs` import (previously
+ * missing in platform.js — a latent Linux bug swallowed by the try/catch).
+ */
+export function winHomeWsl() {
+  if (process.env.QWEN_WIN_HOME_WSL) return process.env.QWEN_WIN_HOME_WSL;
+  const win = process.env.QWEN_WIN_HOME || (IS_WINDOWS ? os.homedir() : "");
+  const m = win.match(/^([a-zA-Z]):[\\\/](.*)$/);
+  if (m) return `/mnt/${m[1].toLowerCase()}/${m[2].replace(/\\/g, "/")}`;
+  if (!IS_WINDOWS) {
+    const candidates = [
+      `/mnt/c/Users/${wslUser()}`,
+      `/mnt/c/Users/${process.env.USER || ""}`,
+      `/mnt/c/Users/${process.env.LOGNAME || ""}`,
+    ];
+    for (const c of candidates) {
+      try {
+        if (c && c !== "/mnt/c/Users/" && fs.existsSync(c)) return c;
+      } catch {}
+    }
+  }
+  return "";
+}
+
+// ---------------------------------------------------------------------------
+// WSL availability probe
+// ---------------------------------------------------------------------------
+
+let _wslAvailable = null;
+
+/**
+ * Probe whether WSL is available on this host.
+ * - Non-Windows (Linux/macOS): always true (no WSL needed; commands run
+ *   directly via bash).
+ * - Windows: runs `wsl.exe --list --quiet` and checks for a non-empty
+ *   output (at least one installed distro). Result is cached.
+ *
+ * Never throws. Returns a boolean.
+ *
+ * @returns {boolean}
+ */
+export function wslAvailable() {
+  if (!IS_WINDOWS) return true;
+  if (_wslAvailable !== null) return _wslAvailable;
+  try {
+    const out = execFileSync("wsl.exe", ["--list", "--quiet"], {
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const lines = out
+      .toString()
+      .split(/\r?\n/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+    _wslAvailable = lines.length > 0;
+  } catch {
+    _wslAvailable = false;
+  }
+  return _wslAvailable;
+}
+
+/** Clear the WSL availability cache. Test-only. */
+export function _resetWslAvailableCache() {
+  _wslAvailable = null;
+}

package/stream_proxy.js

@@ -0,0 +1,453 @@
+#!/usr/bin/env node
+/**
+ * Universal Stateful UTF-8, SSE Stream Sanitizer & Inbound Multimodal Guard Proxy
+ *
+ * Architecture:
+ * - Listens on: 127.0.0.1:18022 (STREAM_PROXY_PORT or VLLM_PROXY_PORT)
+ * - Upstream:   127.0.0.1:18020 (vLLM Engine)
+ *
+ * Capabilities:
+ * 1. Inbound Multimodal Guard:
+ *    When clients send image_url/image blocks, intercepts and converts them
+ *    to descriptive text placeholders before reaching vLLM, preventing
+ *    "Bad request (400): At most 0 image(s) may be provided in one prompt".
+ * 2. Stateful UTF-8 Reconstruction:
+ *    Maintains per-stream TextDecoder with { stream: true } to assemble split
+ *    multi-byte UTF-8 sequences (math symbols, superscripts 2³, Greek letters,
+ *    emojis) across raw TCP/SSE chunk boundaries.
+ * 3. Mid-Stream Error Translation:
+ *    Intercepts mid-stream vLLM error payloads (`data: {"error": ...}`) that
+ *    lack `choices` and converts them into valid completion delta chunks before
+ *    client parsers see them, eliminating `Stream decode error`.
+ * 4. Transparent Pass-Through:
+ *    Non-SSE / non-chat requests (GET /v1/models, embeddings, health) are piped directly.
+ * 5. Zero External Dependencies:
+ *    Standard Node.js http/url modules, runs under WSL2 Linux and Windows.
+ */
+
+import http from "http";
+import { RepetitionDetector, GUARD_MARKER_TEMPLATE } from "./src/repetition_detector.js";
+import { PROXY_MAX_BODY_BYTES } from "./src/config.js";
+
+const UPSTREAM_PORT = parseInt(process.env.VLLM_PORT || "18020", 10);
+// Accept either STREAM_PROXY_PORT (preferred) or VLLM_PROXY_PORT (legacy).
+const PROXY_PORT = parseInt(
+  process.env.STREAM_PROXY_PORT || process.env.VLLM_PROXY_PORT || "18022",
+  10
+);
+// P15: bind loopback only — a LAN-reachable proxy lets any remote client
+// drive the MAX_SEQS=1 GPU queue and wedge the engine for local clients.
+// WSL2 localhost-forwarding keeps it reachable from the Windows host.
+const PROXY_HOST = process.env.VLLM_PROXY_HOST || "127.0.0.1";
+
+function forwardToUpstream(req, res, reqBodyBuffer) {
+  // Disable socket-level timeouts on incoming client connection
+  if (req.socket) {
+    req.socket.setTimeout(0);
+    req.socket.setKeepAlive(true, 10000);
+    req.socket.setNoDelay(true);
+  }
+
+  const headers = { ...req.headers, host: `127.0.0.1:${UPSTREAM_PORT}` };
+  if (reqBodyBuffer) {
+    headers["content-length"] = reqBodyBuffer.length;
+  }
+
+  const isStreamRequest = req.url.startsWith("/v1/chat/completions") && (
+    (req.headers["accept"] && req.headers["accept"].includes("text/event-stream")) ||
+    (reqBodyBuffer && (reqBodyBuffer.includes('"stream":true') || reqBodyBuffer.includes('"stream": true')))
+  );
+
+  let pingInterval = null;
+  let hasDone = false;
+
+  // P7b: per-request lifecycle observability. Before this pass the proxy
+  // logged NOTHING per request — when a task died of engine_empty_response,
+  // the proxy log was empty and the death was undecidable from here. One
+  // stderr line per streaming request now records the whole story:
+  // ttft (first upstream byte), bytes forwarded, duration, and the end cause.
+  // "upstream-end-no-done" is the killer signature (stream closed by the
+  // upstream without any finish_reason); "client-early-close" means the
+  // consumer hung up first. The guard makes the first cause win.
+  const lifecycle = {
+    t0: Date.now(),
+    ttft: null,
+    bytes: 0,
+    logged: false,
+    log(cause) {
+      if (this.logged) return;
+      this.logged = true;
+      console.error(
+        `[StreamProxy] ${req.method} ${req.url} ttft=${this.ttft ?? "never"} bytes=${this.bytes} dur=${Date.now() - this.t0}ms end=${cause}`
+      );
+    },
+  };
+
+  const upstreamUrl = `http://127.0.0.1:${UPSTREAM_PORT}${req.url}`;
+  const upstreamReq = http.request(
+    upstreamUrl,
+    {
+      method: req.method,
+      headers,
+      agent: false,
+    },
+    (upstreamRes) => {
+      const contentType = upstreamRes.headers["content-type"] || "";
+      const isEventStream = contentType.includes("text/event-stream") || isStreamRequest;
+
+      // Non-streaming endpoint: pipe directly
+      if (!isEventStream) {
+        res.writeHead(upstreamRes.statusCode, upstreamRes.headers);
+        upstreamRes.pipe(res);
+        return;
+      }
+
+      // If upstream returned an HTTP error (e.g. 400 or 500), forward status and error body directly
+      if (upstreamRes.statusCode >= 400) {
+        let errBody = "";
+        const expectedLen = parseInt(upstreamRes.headers["content-length"] || "0", 10);
+        function emitError() {
+          if (hasDone) return;
+          hasDone = true;
+          if (pingInterval) clearInterval(pingInterval);
+          if (!res.headersSent) {
+            res.writeHead(upstreamRes.statusCode, upstreamRes.headers);
+            res.end(errBody);
+          } else {
+            // Mid-stream error: emit explicit SSE error event and end
+            res.end(`event: error\ndata: ${errBody}\n\n`);
+          }
+          upstreamReq.destroy();
+        }
+        upstreamRes.on("data", (c) => {
+          errBody += c.toString("utf8");
+          if (expectedLen > 0 && Buffer.byteLength(errBody, "utf8") >= expectedLen) {
+            emitError();
+          }
+        });
+        upstreamRes.on("end", emitError);
+        return;
+      }
+
+      // If headers were not pre-flushed, flush them now
+      if (!res.headersSent) {
+        const cleanHeaders = { ...upstreamRes.headers };
+        delete cleanHeaders["content-length"];
+        delete cleanHeaders["transfer-encoding"];
+
+        res.writeHead(upstreamRes.statusCode, {
+          ...cleanHeaders,
+          "content-type": "text/event-stream; charset=utf-8",
+          "cache-control": "no-cache, no-transform",
+          connection: "keep-alive",
+        });
+
+        pingInterval = setInterval(() => {
+          try {
+            res.write(": keep-alive\n\n");
+          } catch {}
+        }, 5000);
+      }
+
+      const decoder = new TextDecoder("utf-8", { fatal: false, ignoreBOM: true });
+      const repetitionDetector = new RepetitionDetector();
+      let lineBuffer = "";
+
+      upstreamRes.on("data", (chunk) => {
+        const text = decoder.decode(chunk, { stream: true });
+        if (!text) return;
+        lifecycle.ttft ??= Date.now() - lifecycle.t0;
+        lifecycle.bytes += Buffer.byteLength(text);
+
+        lineBuffer += text;
+        if (lineBuffer.includes("data: [DONE]")) {
+          hasDone = true;
+          if (pingInterval) clearInterval(pingInterval);
+          res.write("data: [DONE]\n\n");
+          res.end();
+          return;
+        }
+        const lines = lineBuffer.split("\n");
+        lineBuffer = lines.pop(); // Retain incomplete trailing line
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (trimmed === "data: [DONE]") {
+            hasDone = true;
+            if (pingInterval) clearInterval(pingInterval);
+            res.write("data: [DONE]\n\n");
+            res.end();
+            return;
+          } else if (trimmed.startsWith("data: ")) {
+            const jsonPayload = trimmed.slice(6).trim();
+            if (jsonPayload.startsWith("{")) {
+              try {
+                const parsed = JSON.parse(jsonPayload);
+                if (parsed.error && !parsed.choices) {
+                  const errMsg = parsed.error.message || JSON.stringify(parsed.error);
+                  if (pingInterval) clearInterval(pingInterval);
+                  hasDone = true;
+                  res.end(`event: error\ndata: ${JSON.stringify(parsed)}\n\n`);
+                  upstreamReq.destroy();
+                  return;
+                }
+
+                // Check for degenerate runaway repetition in token deltas (content or reasoning).
+                // Engine emits reasoning as `delta.reasoning` (--reasoning-parser qwen3, P2d live SSE
+                // evidence); `reasoning_content` kept as legacy fallback. Both must feed the detector
+                // or a reasoning-level repetition loop burns the full max_tokens budget invisibly
+                // (P7b root cause: ~18-min single generation, spec-decode acceptance pinned at 8.0).
+                const delta = parsed?.choices?.[0]?.delta;
+                if (delta) {
+                  const tokenText = delta.content || delta.reasoning || delta.reasoning_content || "";
+                  if (tokenText) {
+                    let rep;
+                    try {
+                      rep = repetitionDetector.feed(tokenText);
+                    } catch (detErr) {
+                      console.error(`[StreamProxy] Repetition detector error: ${detErr.message}; truncating stream.`);
+                      if (pingInterval) clearInterval(pingInterval);
+                      hasDone = true;
+                      res.write(`data: ${JSON.stringify({ id: "chatcmpl-det-err", object: "chat.completion.chunk", created: Math.floor(Date.now() / 1000), model: "qwen3.8-27b", choices: [{ index: 0, delta: { content: "[Stream truncated: repetition detector error]" }, finish_reason: "stop" }] })}\n\ndata: [DONE]\n\n`);
+                      res.end();
+                      upstreamReq.destroy();
+                      return;
+                    }
+                    if (rep) {
+                      console.error(`[StreamProxy Circuit Breaker] Runaway repetition detected (${rep.type}: ${JSON.stringify(rep.pattern)}, count: ${rep.count}). Safely aborting stream.`);
+                      lifecycle.log(`repetition-breaker(${rep.type})`);
+                      if (pingInterval) clearInterval(pingInterval);
+                      hasDone = true;
+                      const breakerChunk = {
+                        id: "chatcmpl-repetition-breaker",
+                        object: "chat.completion.chunk",
+                        created: Math.floor(Date.now() / 1000),
+                        model: "qwen3.8-27b",
+                        choices: [
+                          {
+                            index: 0,
+                            // M3b: marker text comes from the GUARD_MARKER_TEMPLATE
+                            // sentinel (single source of truth in repetition_detector.js).
+                            delta: { content: GUARD_MARKER_TEMPLATE.replaceAll("${type}", rep.type).replaceAll("${pattern}", JSON.stringify(rep.pattern)) },
+                            finish_reason: "stop",
+                          },
+                        ],
+                      };
+                      res.write(`data: ${JSON.stringify(breakerChunk)}\n\ndata: [DONE]\n\n`);
+                      res.end();
+                      upstreamReq.destroy();
+                      return;
+                    }
+                  }
+                }
+              } catch {}
+            }
+          }
+          res.write(line + "\n");
+        }
+      });
+
+      upstreamRes.on("end", () => {
+        lifecycle.log(hasDone ? "done" : "upstream-end-no-done");
+        if (pingInterval) clearInterval(pingInterval);
+        const tail = decoder.decode();
+        if (tail) {
+          lineBuffer += tail;
+        }
+        if (lineBuffer) {
+          res.write(lineBuffer + (lineBuffer.endsWith("\n") ? "\n" : "\n\n"));
+          if (lineBuffer.includes("[DONE]")) {
+            hasDone = true;
+          }
+        }
+        res.end();
+      });
+
+      upstreamRes.on("error", (err) => {
+        lifecycle.log(`upstream-error(${err ? (err.message || String(err)) : "unknown"})`);
+        if (pingInterval) clearInterval(pingInterval);
+        try {
+          if (!hasDone) {
+            hasDone = true;
+            res.end(`event: error\ndata: ${JSON.stringify({ error: { message: errMsg, type: "upstream_error" } })}\n\n`);
+          } else {
+            res.end();
+          }
+        } catch {}
+      });
+
+      res.on("close", () => {
+        // Normal completions log via the upstream 'end' handler first; a close
+        // with hasDone still false means the CONSUMER hung up early.
+        if (!hasDone) lifecycle.log("client-early-close");
+        if (pingInterval) clearInterval(pingInterval);
+        upstreamReq.destroy();
+      });
+    }
+  );
+
+  upstreamReq.setTimeout(0);
+
+  upstreamReq.on("error", (err) => {
+    if (isStreamRequest) lifecycle.log(`connect-error(${err ? err.message : "unknown"})`);
+    if (pingInterval) clearInterval(pingInterval);
+    if (!res.headersSent) {
+      res.writeHead(502, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: { message: `vLLM upstream connection error: ${err.message}`, type: "upstream_connection_error" } }));
+    } else {
+      try {
+        res.end(`event: error\ndata: ${JSON.stringify({ error: { message: err.message, type: "upstream_connection_error" } })}\n\n`);
+      } catch {}
+    }
+  });
+
+  if (reqBodyBuffer) {
+    upstreamReq.end(reqBodyBuffer);
+  } else {
+    req.pipe(upstreamReq);
+  }
+}
+
+const server = http.createServer((req, res) => {
+  // Local health check
+  if (req.url === "/health") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    return res.end(
+      JSON.stringify({
+        status: "ok",
+        service: "mcp-castor-stream-proxy",
+        upstream_port: UPSTREAM_PORT,
+        proxy_port: PROXY_PORT,
+        pid: process.pid,
+      })
+    );
+  }
+
+  // Deep sanitize incoming chat completions requests to guard against multimodal image crashes
+  if (req.method === "POST" && req.url.startsWith("/v1/chat/completions")) {
+    const chunks = [];
+    let byteCount = 0;
+    // D13 (FX6): single source for the inbound body limit — imported from
+    // config.js (PROXY_MAX_BODY_BYTES). The old inline 50MB literal was a
+    // dual-source drift risk against config.js; it is gone.
+    let exceeded = false;
+
+    req.on("data", (chunk) => {
+      if (exceeded) return;
+      byteCount += chunk.length;
+      if (byteCount > PROXY_MAX_BODY_BYTES) {
+        exceeded = true;
+        res.writeHead(413, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            error: {
+              message: `Payload Too Large: request body exceeded ${PROXY_MAX_BODY_BYTES} bytes limit.`,
+              type: "payload_too_large",
+              code: 413,
+            },
+          })
+        );
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (exceeded) return;
+      const rawBody = Buffer.concat(chunks);
+      try {
+        const bodyStr = rawBody.toString("utf8");
+        const visionEnabled =
+          process.env.VISION === "1" || process.env.ENABLE_VISION === "1";
+        if (
+          !visionEnabled &&
+          (bodyStr.includes('"image"') ||
+            bodyStr.includes('"image_url"') ||
+            bodyStr.includes('"input_image"') ||
+            bodyStr.includes('"image_file"') ||
+            bodyStr.includes("data:image/"))
+        ) {
+          const body = JSON.parse(bodyStr);
+          let modified = false;
+
+          function sanitizeItem(item) {
+            if (!item) return item;
+            if (typeof item === "string") return item;
+            if (Array.isArray(item)) {
+              return item.map(sanitizeItem);
+            }
+            if (typeof item === "object") {
+              const type = item.type;
+              if (
+                type === "image_url" ||
+                type === "image" ||
+                type === "input_image" ||
+                type === "image_file" ||
+                item.image ||
+                item.image_url
+              ) {
+                modified = true;
+                return {
+                  type: "text",
+                  text: "[Image file omitted: Local Qwen3.8-27B runs in pure text mode for Universal 245K context. Images must be inspected multimodally by the Lead Architect.]",
+                };
+              }
+              for (const k of Object.keys(item)) {
+                item[k] = sanitizeItem(item[k]);
+              }
+            }
+            return item;
+          }
+
+          if (Array.isArray(body.messages)) {
+            for (const msg of body.messages) {
+              msg.content = sanitizeItem(msg.content);
+            }
+          }
+          if (body.prompt) {
+            body.prompt = sanitizeItem(body.prompt);
+          }
+
+          if (modified) {
+            const sanitizedBuffer = Buffer.from(JSON.stringify(body), "utf8");
+            return forwardToUpstream(req, res, sanitizedBuffer);
+          }
+        }
+      } catch (err) {
+        // Fall back to piping raw body if parsing fails
+      }
+      forwardToUpstream(req, res, rawBody);
+    });
+    return;
+  }
+
+  forwardToUpstream(req, res, null);
+});
+
+server.on("error", (err) => {
+  if (err.code === "EADDRINUSE") {
+    console.error(`[StreamProxy] Port ${PROXY_PORT} is already in use — port conflict is a failure, not a success.`);
+    process.exit(1);
+  } else {
+    console.error("[StreamProxy] Server error:", err);
+    process.exit(1);
+  }
+});
+
+// Disable Node.js server timeouts so long-running reasoning streams on 245K context never get killed
+server.timeout = 0;
+server.requestTimeout = 0;
+server.headersTimeout = 0;
+server.keepAliveTimeout = 0;
+
+server.listen(PROXY_PORT, PROXY_HOST, () => {
+  console.log(`[StreamProxy] Universal stream proxy listening on ${PROXY_HOST}:${PROXY_PORT} -> 127.0.0.1:${UPSTREAM_PORT}`);
+});
+
+process.on("SIGTERM", () => {
+  server.close(() => process.exit(0));
+});
+
+process.on("SIGINT", () => {
+  server.close(() => process.exit(0));
+});