@thincoder/core 0.9.1

package/mcp/helpers.mjs

@@ -0,0 +1,51 @@
+/**
+ * mcp/helpers.mjs — MCP shared utility functions and constants
+ */
+
+export const INIT_TIMEOUT_MS = 30_000
+export const CALL_TIMEOUT_MS = 120_000
+export const ENDPOINT_WAIT_MS = 5_000
+
+let nextRpcId = 0
+/** Generate a unique incrementing RPC ID string */
+export function rpcId() {
+  return String(++nextRpcId)
+}
+
+/** Race a promise against a timeout, rejecting after ms milliseconds */
+export function withTimeout(promise, ms) {
+  let timer
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`timeout after ${ms}ms`)), ms)
+    timer.unref?.()
+  })
+  return Promise.race([promise.finally(() => clearTimeout(timer)), timeout])
+}
+
+/** Quote a shell argument: wrap in double-quotes if it contains whitespace or quotes */
+export function quoteArg(s) {
+  return /[\s"]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s
+}
+
+/** Convert an Authorization Bearer token into a WebSocket subprotocol.
+ *  2026-08-31 MCP 会诊 #10：原实现把 token 塞进 URL query——代理/网关日志会泄露凭证，
+ *  且无标准依据。Node 内置 WebSocket（undici）无法自定义请求头，MCP 生态的标准替代
+ *  通道是 subprotocol（`bearer.<token>`）。用户 URL 自带的 query token 不动（兼容）。
+ *  @returns {{ url: string, protocols: string[] }} — protocols 为空数组表示无认证。 */
+export function withAuthToken(wsUrl, authorization) {
+  if (!authorization) return { url: wsUrl, protocols: [] }
+  const token = authorization.replace(/^Bearer\s+/i, "")
+  let u
+  try {
+    u = new URL(wsUrl)
+  } catch {
+    throw new Error(`Invalid WebSocket URL: ${String(wsUrl).slice(0, 120)}`)
+  }
+  // subprotocol 不进入 URL/日志，token 不再注入 query
+  return { url: u.href, protocols: [`bearer.${token}`] }
+}
+
+/** Sanitize a tool name: replace non-alphanumeric chars with underscores, cap at 64 chars */
+export function sanitizeToolName(name) {
+  return name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64)
+}

package/mcp/transport-http.mjs

@@ -0,0 +1,248 @@
+/**
+ * mcp/transport-http.mjs — MCP HTTP + SSE transport (Streamable HTTP)
+ */
+import { rpcId, CALL_TIMEOUT_MS, ENDPOINT_WAIT_MS, INIT_TIMEOUT_MS, withTimeout } from "./helpers.mjs"
+
+/** Create an MCP HTTP+SSE transport for Streamable HTTP servers */
+export function httpTransport(baseURL, extraHeaders = {}) {
+  const url = baseURL.replace(/\/+$/, "")
+  let sessionId = null
+  let closed = false
+  let eventSource = null
+  // 2026-09-01 MCP.md §4 D-1：GET SSE 不可用（405/不支持）降级后的纯 POST 模式标记。
+  // POST-only server（如 glm-websearch）无流可断：isAlive 不得因 eventSource == null 判死。
+  let postOnly = false
+  let abortController = null
+  let postUrl = url
+  let legacySSE = false
+  let deadFired = false
+  let deadListeners = new Set()
+
+  /** 2026-08-31 MCP 会诊 P5：意外死亡通知（SSE 流断/error，非主动 close）。 */
+  const fireDead = (msg) => {
+    if (deadFired) return
+    deadFired = true
+    for (const cb of deadListeners) { try { cb(msg) } catch { /* listener error */ } }
+  }
+  const onDead = (cb) => { deadListeners.add(cb); return () => deadListeners.delete(cb) }
+
+  const headers = () => {
+    const h = { "Content-Type": "application/json", Accept: "text/event-stream, application/json", ...extraHeaders }
+    if (sessionId) h["Mcp-Session-Id"] = sessionId
+    return h
+  }
+
+  const pending = new Map()
+
+  async function* parseSSE(response) {
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let buf = ""
+    let current = { data: "", event: "message" }
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        buf += decoder.decode(value, { stream: true })
+        const lines = buf.split("\n")
+        buf = lines.pop() ?? ""
+        for (const raw of lines) {
+          const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw
+          if (line === "") {
+            if (current.data) {
+              yield { event: current.event, data: current.data.trimEnd() }
+              current = { data: "", event: "message" }
+            }
+          } else if (line.startsWith("data:")) {
+            current.data += (current.data ? "\n" : "") + line.slice(5).replace(/^ /, "")
+          } else if (line.startsWith("event:")) {
+            current.event = line.slice(6).trim()
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock()
+    }
+  }
+
+  async function openSSE() {
+    if (closed) return
+    abortController?.abort()
+    abortController = new AbortController()
+    const signal = AbortSignal.any([abortController.signal, AbortSignal.timeout(INIT_TIMEOUT_MS)])
+    const resp = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "text/event-stream", ...extraHeaders },
+      signal,
+    })
+    if (!resp.ok) throw new Error(`SSE connect failed: HTTP ${resp.status}`)
+    eventSource = parseSSE(resp)
+    let endpointReady
+    const gotEndpoint = new Promise((resolve) => { endpointReady = resolve })
+
+    ;(async () => {
+      try {
+        for await (const { event, data } of eventSource) {
+          if (closed) break
+          if (event === "endpoint") {
+            postUrl = new URL(data.trim(), url).href
+            legacySSE = true
+            endpointReady()
+            continue
+          }
+          try {
+            const msg = JSON.parse(data)
+            const resolver = pending.get(msg.id)
+            if (resolver) {
+              pending.delete(msg.id)
+              resolver(msg)
+            }
+          } catch { /* not JSON, ignore */ }
+        }
+        // 正常走完 = server 关闭了流（网络/对端退出）→ 非主动关闭视为死亡
+        if (!closed) fireDead("SSE stream ended")
+      } catch (error) {
+        const wasClosed = closed
+        if (!wasClosed) {
+          for (const [, resolve] of pending) resolve({ id: null, error: { code: -32000, message: `SSE error: ${error.message}` } })
+          pending.clear()
+          fireDead(`SSE error: ${error.message}`)
+        }
+      }
+    })()
+
+    const wait = new Promise((resolve) => {
+      const t = setTimeout(resolve, ENDPOINT_WAIT_MS)
+      t.unref?.()
+    })
+    await Promise.race([gotEndpoint, wait])
+  }
+
+  async function postRequest(method, params) {
+    const id = rpcId()
+    const body = JSON.stringify({ jsonrpc: "2.0", id, method, params })
+
+    if (legacySSE) {
+      // 2026-08-31 MCP 会诊 #10：legacy 模式下 POST 若直接带回 JSON-RPC body（违规 server，
+      // 规范是响应经 GET SSE 流回）——原实现对 resp.ok 什么都不做 → pending 挂满 120s。
+      // 空 body = 规范行为（等待 SSE 流）；非空 JSON = 违规 server，直接解析 resolve。
+      return new Promise((resolve) => {
+        pending.set(id, resolve)
+        fetch(postUrl, { method: "POST", headers: headers(), body, signal: AbortSignal.timeout(CALL_TIMEOUT_MS) })
+          .then(async (resp) => {
+            if (!resp.ok) {
+              pending.delete(id)
+              resolve({ id, error: { code: -32000, message: `POST failed: HTTP ${resp.status}` } })
+              return
+            }
+            const raw = await resp.text().catch(() => "")
+            if (raw.trim()) {
+              try {
+                const msg = JSON.parse(raw)
+                if (msg.id === id) { pending.delete(id); resolve(msg); return }
+              } catch { /* ignore — pending 交给 SSE 流 */ }
+            }
+            // 空体或非本次 id 的 JSON：保持 pending 等 GET SSE 流回包
+          })
+          .catch((e) => {
+            pending.delete(id)
+            resolve({ id, error: { code: -32000, message: `POST failed: ${e.message}` } })
+          })
+      }).finally(() => pending.delete(id))
+    }
+
+    // 2026-08-31 MCP 会诊 P4：Streamable HTTP 规范路径（POST→202→GET SSE 回包）。
+    // 原实现非 legacy 分支从不注册 pending：202 空 body → resp.json() 抛 SyntaxError，
+    // 而 SSE 流里 pending.get(id) 永远 miss——每次调用挂满 120s。
+    // 现在两类通道统一：先注册 pending，POST 得到的结果（直接 body / SSE / 202 等待）
+    // 都经 pending resolve；SSE 流由 openSSE() 转发。200+JSON 直接 body 解析。
+    return new Promise((resolve) => {
+      pending.set(id, resolve)
+      fetch(postUrl, { method: "POST", headers: headers(), body, signal: AbortSignal.timeout(CALL_TIMEOUT_MS) })
+        .then(async (resp) => {
+          const ct = resp.headers.get("content-type") ?? ""
+          const newSessionId = resp.headers.get("Mcp-Session-Id")
+          if (newSessionId) sessionId = newSessionId
+          // 202: 已接受，响应将经 GET SSE 流回——pending 保持，由 openSSE 转发 resolve
+          if (resp.status === 202) return
+          if (!resp.ok) {
+            pending.delete(id)
+            resolve({ id, error: { code: -32000, message: `HTTP ${resp.status}` } })
+            return
+          }
+          if (ct.includes("text/event-stream")) {
+            // 响应体本身就是一条 SSE（一次性流）：解析匹配该 id
+            try {
+              for await (const { data } of parseSSE(resp)) {
+                try {
+                  const msg = JSON.parse(data)
+                  if (msg.id === id) { pending.delete(id); resolve(msg); return }
+                } catch { /* skip */ }
+              }
+              pending.delete(id)
+              resolve({ id, error: { code: -32000, message: "No JSON-RPC response in SSE stream" } })
+            } catch (e) {
+              pending.delete(id)
+              resolve({ id, error: { code: -32000, message: `SSE response failed: ${e.message}` } })
+            }
+            return
+          }
+          // 直接 JSON body：拿掉 pending 立即解析
+          pending.delete(id)
+          try {
+            resolve(await resp.json())
+          } catch (e) {
+            resolve({ id, error: { code: -32000, message: `invalid JSON body: ${e.message}` } })
+          }
+        })
+        .catch((e) => {
+          if (pending.delete(id)) {
+            resolve({ id, error: { code: -32000, message: `POST failed: ${e.message}` } })
+          }
+        })
+    }).finally(() => pending.delete(id))
+  }
+
+  const send = async (method, params) => withTimeout(postRequest(method, params), CALL_TIMEOUT_MS)
+
+  const notify = (method, params) => {
+    fetch(postUrl, {
+      method: "POST",
+      headers: headers(),
+      body: JSON.stringify({ jsonrpc: "2.0", method, params }),
+      signal: AbortSignal.timeout(10_000),
+    }).catch((e) => {
+      // notify is fire-and-forget by design, but log network errors for debugging
+      if (e.name !== "AbortError") console.error(`[mcp] notify failed: ${e.message}`)
+    })
+  }
+
+  const close = () => {
+    closed = true
+    abortController?.abort()
+    if (sessionId) {
+      fetch(postUrl, {
+        method: "DELETE",
+        headers: { "Mcp-Session-Id": sessionId, ...extraHeaders },
+        signal: AbortSignal.timeout(5_000),
+      }).catch((e) => {
+        // close is best-effort cleanup; log but don't throw
+        if (e.name !== "AbortError") console.error(`[mcp] close DELETE failed: ${e.message}`)
+      })
+      sessionId = null
+    }
+    for (const [, resolve] of pending) resolve({ id: null, error: { code: -32000, message: "Connection closed" } })
+    pending.clear()
+  }
+
+  /** D-1：openSSE 降级（GET 405/不支持）后由 connect 链调用——标记纯 Streamable POST 模式 */
+  const markPostOnly = () => { postOnly = true }
+
+  return {
+    send, notify, close, openSSE, url, headers: extraHeaders,
+    // F1：POST-only 降级（postOnly）与 legacy SSE 流（eventSource）都算活连接——
+    // 不得因 eventSource == null 误判死（glm-websearch "reconnect failed" 根因）。
+    isAlive: () => !closed && (eventSource != null || postOnly),
+    onDead, markPostOnly,
+  }
+}

package/mcp/transport-stdio.mjs

@@ -0,0 +1,140 @@
+/**
+ * mcp/transport-stdio.mjs — MCP stdio transport
+ */
+import { spawn } from "node:child_process"
+import { rpcId, CALL_TIMEOUT_MS, withTimeout, quoteArg } from "./helpers.mjs"
+
+/** Kill the child AND its whole process tree.
+ *  win32: cmd.exe 包装 spawn 的孙进程（npx/node）必须 taskkill /T /F 才能杀净
+ *  （2026-08-31 MCP 会诊 P2：此前只 child.kill() 杀 cmd.exe 壳，真 server 成僵尸
+ *  并在 Windows 团队每人每次断开/重连泄漏一批）；
+ *  POSIX: SIGTERM 后 2s 未退 SIGKILL 兜底。 */
+function killTree(child) {
+  if (!child.pid) return
+  if (process.platform === "win32") {
+    try { spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }) } catch { /* best effort */ }
+    return
+  }
+  try {
+    child.kill("SIGTERM")
+    setTimeout(() => { try { child.kill("SIGKILL") } catch { /* already gone */ } }, 2000).unref?.()
+  } catch { /* best effort */ }
+}
+
+/** Create an MCP stdio transport over a spawned child process.
+ *  @param {Object} [env] — extra environment variables merged on top of process.env */
+export function stdioTransport(command, args, env) {
+  const spawnOptions = { stdio: ["pipe", "pipe", "pipe"], windowsHide: true, env: { ...process.env, ...env } }
+  const child =
+    process.platform === "win32" && !/\.exe$/i.test(command)
+      ? spawn("cmd.exe", ["/d", "/s", "/c", [command, ...(args ?? [])].map(quoteArg).join(" ")], {
+          ...spawnOptions,
+          windowsVerbatimArguments: true,
+        })
+      : spawn(command, args ?? [], spawnOptions)
+
+  const pending = new Map()
+  const decoder = new TextDecoder()
+  let buffer = ""
+  let stderrTail = ""
+  let spawnError = null
+  let closed = false
+  let deadFired = false
+  let deadListeners = new Set()
+
+  /** 2026-08-31 MCP 会诊 P5：意外死亡通知（进程自杀/崩溃，非主动 close）。
+   *  主动 close() 先置 closed → 后续 close 事件不触发。 */
+  const fireDead = (msg) => {
+    if (deadFired) return
+    deadFired = true
+    for (const cb of deadListeners) { try { cb(msg) } catch { /* listener error */ } }
+  }
+  const onDead = (cb) => { deadListeners.add(cb); return () => deadListeners.delete(cb) }
+
+  const failAll = (message) => {
+    for (const [, resolve] of pending) resolve({ id: null, error: { code: -32000, message } })
+    pending.clear()
+  }
+
+  child.stdout.on("data", (chunk) => {
+    buffer += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true })
+    const lines = buffer.split("\n")
+    buffer = lines.pop() ?? ""
+    for (const line of lines) {
+      if (!line.trim()) continue
+      try {
+        const msg = JSON.parse(line)
+        const resolver = pending.get(msg.id)
+        if (resolver) {
+          pending.delete(msg.id)
+          resolver(msg)
+        }
+      } catch { /* non-JSON line, ignore */ }
+    }
+  })
+
+  child.stderr.on("data", (chunk) => {
+    stderrTail = (stderrTail + chunk.toString()).slice(-2000)
+  })
+
+  child.stdin.on("error", () => {})
+  child.on("error", (error) => {
+    spawnError = error
+    closed = true
+    failAll(`spawn failed: ${error.message}`)
+  })
+  child.on("close", () => {
+    const wasClosed = closed // 主动 close() 先置 closed → 意外事件不重复
+    closed = true
+    const lastLine = stderrTail.trim().split("\n").pop()
+    failAll(`Connection closed${lastLine ? ` | stderr: ${lastLine}` : ""}`)
+    if (!wasClosed) fireDead(`MCP server process exited${lastLine ? ` | stderr: ${lastLine}` : ""}`)
+  })
+
+  const send = (method, params, signal) => {
+    if (spawnError) return Promise.resolve({ id: null, error: { code: -32000, message: `spawn failed: ${spawnError.message}` } })
+    if (closed) return Promise.reject(new Error("MCP connection closed"))
+    const id = rpcId()
+    let resolveFn
+    const promise = new Promise((resolve) => { resolveFn = resolve; pending.set(id, resolve) })
+    // 2026-08-31 MCP 会诊 P7：上层 signal 中断时即刻作废 pending（原实现等满
+    // CALL_TIMEOUT_MS 才清）并向 server 发 cancelled 通知。
+    const onAbort = () => {
+      pending.delete(id)
+      try { notify("notifications/cancelled", { requestId: id }) } catch { /* ignore */ }
+      resolveFn({ id, error: { code: -32000, message: "Request cancelled by user" } })
+    }
+    if (signal) {
+      if (signal.aborted) return Promise.reject((signal.reason instanceof Error) ? signal.reason : new DOMException("Aborted", "AbortError"))
+      signal.addEventListener("abort", onAbort, { once: true })
+      promise.finally(() => signal.removeEventListener("abort", onAbort)).catch?.(() => {})
+    }
+    try {
+      child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n")
+    } catch (error) {
+      pending.delete(id)
+      return Promise.resolve({ id: null, error: { code: -32000, message: `stdin write failed: ${error.message}` } })
+    }
+    return withTimeout(promise, CALL_TIMEOUT_MS).finally(() => pending.delete(id))
+  }
+
+  const notify = (method, params) => {
+    if (closed) return
+    try {
+      child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n")
+    } catch { /* ignore */ }
+  }
+
+  return {
+    send, notify,
+    close: () => {
+      // 2026-08-31 MCP 会诊 P2：close ≠ 只杀进程——先置 closed + failAll（在途请求
+      // 立即得到 "Connection closed" 而非挂满 120s），再杀整个进程树。
+      closed = true
+      failAll("Connection closed")
+      if (child.exitCode === null) killTree(child)
+    },
+    isAlive: () => !closed && !spawnError && child.exitCode === null,
+    onDead,
+  }
+}

package/mcp/transport-ws.mjs

@@ -0,0 +1,122 @@
+/**
+ * mcp/transport-ws.mjs — MCP WebSocket transport
+ */
+import { rpcId, INIT_TIMEOUT_MS, CALL_TIMEOUT_MS, withTimeout, withAuthToken } from "./helpers.mjs"
+
+/** Create an MCP WebSocket transport */
+export function wsTransport(wsUrl, extraHeaders = {}) {
+  const pending = new Map()
+  let closed = false
+  let ws = null
+  let deadFired = false
+  let deadListeners = new Set()
+
+  /** 2026-08-31 MCP 会诊 P5：意外死亡通知（非主动 close 的连接断开）。 */
+  const fireDead = (msg) => {
+    if (deadFired) return
+    deadFired = true
+    for (const cb of deadListeners) { try { cb(msg) } catch { /* listener error */ } }
+  }
+  const onDead = (cb) => { deadListeners.add(cb); return () => deadListeners.delete(cb) }
+
+  const failAll = (message) => {
+    for (const [, resolve] of pending) resolve({ id: null, error: { code: -32000, message } })
+    pending.clear()
+  }
+
+  const connect = () => {
+    if (closed) throw new Error("MCP WebSocket connection closed")
+    // 2026-08-31 MCP 会诊 #10：Authorization 经 subprotocol（bearer.<token>）传递，
+    // 不注入 URL query（防代理/网关日志泄露）；无认证时 protocols 为空数组。
+    const { url: wsUrlResolved, protocols } = withAuthToken(wsUrl, extraHeaders.Authorization)
+    ws = new WebSocket(wsUrlResolved, protocols.length ? protocols : undefined)
+
+    return new Promise((resolve, reject) => {
+      let settled = false
+      const settleErr = (err) => { if (!settled) { settled = true; reject(err) } }
+      const timeout = setTimeout(() => {
+        settleErr(new Error(`WebSocket connect timeout: ${wsUrl}`))
+        try { ws.close() } catch { /* ignore */ }
+      }, INIT_TIMEOUT_MS)
+
+      ws.addEventListener("open", () => {
+        if (settled) return
+        settled = true
+        clearTimeout(timeout)
+        resolve()
+      })
+
+      ws.addEventListener("message", (event) => {
+        try {
+          const msg = JSON.parse(event.data.toString())
+          const resolver = pending.get(msg.id)
+          if (resolver) {
+            pending.delete(msg.id)
+            resolver(msg)
+          }
+        } catch { /* not JSON, ignore */ }
+      })
+
+      ws.addEventListener("error", (event) => {
+        const wasClosed = closed
+        clearTimeout(timeout)
+        closed = true
+        const errMsg = event.message || event.error?.message || "WebSocket error"
+        settleErr(new Error(errMsg))
+        failAll(errMsg)
+        if (!wasClosed) fireDead(errMsg)
+      })
+
+      ws.addEventListener("close", () => {
+        const wasClosed = closed
+        clearTimeout(timeout)
+        closed = true
+        // 2026-08-31 MCP 会诊 P1：握手期间 disconnect（close 先于 open 且无 error）——
+        // 原实现 close 只 clearTimeout + failAll，connect promise 永不 settle（启动挂死）。
+        // settled 标志保证 close 未开成必 reject。
+        settleErr(new Error("WebSocket closed before connection established"))
+        failAll("WebSocket closed")
+        if (!wasClosed) fireDead("WebSocket closed")
+      })
+    })
+  }
+
+  const send = (method, params, signal) => {
+    if (closed) return Promise.reject(new Error("MCP WebSocket connection closed"))
+    const id = rpcId()
+    let resolveFn
+    const promise = new Promise((resolve) => { resolveFn = resolve; pending.set(id, resolve) })
+    // 2026-08-31 MCP 会诊 P7：abort 即刻作废 pending + 发 cancelled（原等满 120s）
+    if (signal) {
+      if (signal.aborted) return Promise.reject(new DOMException("Aborted", "AbortError"))
+      const onAbort = () => {
+        pending.delete(id)
+        try { notify("notifications/cancelled", { requestId: id }) } catch { /* ignore */ }
+        resolveFn({ id, error: { code: -32000, message: "Request cancelled by user" } })
+      }
+      signal.addEventListener("abort", onAbort, { once: true })
+      promise.finally(() => signal.removeEventListener("abort", onAbort)).catch?.(() => {})
+    }
+    try {
+      ws.send(JSON.stringify({ jsonrpc: "2.0", id, method, params }))
+    } catch (error) {
+      pending.delete(id)
+      return Promise.resolve({ id: null, error: { code: -32000, message: `ws send failed: ${error.message}` } })
+    }
+    return withTimeout(promise, CALL_TIMEOUT_MS).finally(() => pending.delete(id))
+  }
+
+  const notify = (method, params) => {
+    if (!closed && ws?.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ jsonrpc: "2.0", method, params }))
+    }
+  }
+
+  const close = () => {
+    closed = true
+    failAll("Connection closed")
+    try { ws?.close() } catch { /* ignore */ }
+  }
+
+  return { send, notify, close, connect, isAlive: () => !closed && ws?.readyState === WebSocket.OPEN, onDead }
+}