skalpel 2.0.13 → 2.0.15

package/dist/proxy/index.cjs

@@ -5,6 +5,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -27,27 +30,19 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/proxy/index.ts
-var proxy_exports = {};
-__export(proxy_exports, {
-  getProxyStatus: () => getProxyStatus,
-  loadConfig: () => loadConfig,
-  saveConfig: () => saveConfig,
-  startProxy: () => startProxy,
-  stopProxy: () => stopProxy
-});
-module.exports = __toCommonJS(proxy_exports);
-
-// src/proxy/server.ts
-var import_node_http = __toESM(require("http"), 1);
-
 // src/proxy/dispatcher.ts
-var import_undici = require("undici");
-var skalpelDispatcher = new import_undici.Agent({
-  keepAliveTimeout: 1e4,
-  keepAliveMaxTimeout: 6e4,
-  connections: 100,
-  pipelining: 1
+var import_undici, skalpelDispatcher;
+var init_dispatcher = __esm({
+  "src/proxy/dispatcher.ts"() {
+    "use strict";
+    import_undici = require("undici");
+    skalpelDispatcher = new import_undici.Agent({
+      keepAliveTimeout: 1e4,
+      keepAliveMaxTimeout: 6e4,
+      connections: 100,
+      pipelining: 1
+    });
+  }
 });
 
 // src/proxy/envelope.ts
@@ -116,9 +111,13 @@ function defaultMessageForStatus(status) {
   if (status >= 400) return "Client error";
   return "Error";
 }
+var init_envelope = __esm({
+  "src/proxy/envelope.ts"() {
+    "use strict";
+  }
+});
 
 // src/proxy/recovery.ts
-var import_node_crypto = require("crypto");
 function parseRetryAfterHeader(header) {
   if (!header) return void 0;
   const trimmed = header.trim();
@@ -134,11 +133,10 @@ function parseRetryAfterHeader(header) {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-var MAX_RETRY_AFTER_SECONDS = 60;
-var DEFAULT_BACKOFF_SECONDS = 2;
 async function handle429WithRetryAfter(response, retryFn, logger) {
   const headerVal = response.headers.get("retry-after");
   const parsed = parseRetryAfterHeader(headerVal);
+  logger.debug(`429 recovery retryAfterHeader=${headerVal ?? "none"} parsed=${parsed ?? "none"}`);
   if (parsed === void 0) {
     await sleep(DEFAULT_BACKOFF_SECONDS * 1e3);
     const retried2 = await retryFn();
@@ -146,6 +144,7 @@ async function handle429WithRetryAfter(response, retryFn, logger) {
     return retried2;
   }
   if (parsed > MAX_RETRY_AFTER_SECONDS) {
+    logger.warn(`429 recovery capped: retryAfter=${parsed}s exceeds max=${MAX_RETRY_AFTER_SECONDS}s, passing 429 through`);
     return response;
   }
   await sleep(parsed * 1e3);
@@ -153,12 +152,12 @@ async function handle429WithRetryAfter(response, retryFn, logger) {
   logger.info("proxy.recovery.429_retry_count increment");
   return retried;
 }
-var TIMEOUT_CODES = /* @__PURE__ */ new Set(["ETIMEDOUT", "TIMEOUT", "UND_ERR_HEADERS_TIMEOUT"]);
 async function handleTimeoutWithRetry(err, retryFn, logger) {
   const code = err.code;
   if (!code || !TIMEOUT_CODES.has(code)) {
     throw err;
   }
+  logger.warn(`timeout recovery code=${code}`);
   await sleep(DEFAULT_BACKOFF_SECONDS * 1e3);
   const retried = await retryFn();
   logger.info("proxy.recovery.timeout_retry_count increment");
@@ -168,23 +167,49 @@ function tokenFingerprint(authHeader) {
   if (authHeader === void 0) return "none";
   return (0, import_node_crypto.createHash)("sha256").update(authHeader).digest("hex").slice(0, 12);
 }
-var MUTEX_MAX_ENTRIES = 1024;
-var LruMutexMap = class extends Map {
-  set(key, value) {
-    if (this.has(key)) {
-      super.delete(key);
-    } else if (this.size >= MUTEX_MAX_ENTRIES) {
-      const oldest = this.keys().next().value;
-      if (oldest !== void 0) super.delete(oldest);
-    }
-    return super.set(key, value);
+var import_node_crypto, MAX_RETRY_AFTER_SECONDS, DEFAULT_BACKOFF_SECONDS, TIMEOUT_CODES, MUTEX_MAX_ENTRIES, LruMutexMap, refreshMutex;
+var init_recovery = __esm({
+  "src/proxy/recovery.ts"() {
+    "use strict";
+    import_node_crypto = require("crypto");
+    MAX_RETRY_AFTER_SECONDS = 60;
+    DEFAULT_BACKOFF_SECONDS = 2;
+    TIMEOUT_CODES = /* @__PURE__ */ new Set(["ETIMEDOUT", "TIMEOUT", "UND_ERR_HEADERS_TIMEOUT"]);
+    MUTEX_MAX_ENTRIES = 1024;
+    LruMutexMap = class extends Map {
+      set(key, value) {
+        if (this.has(key)) {
+          super.delete(key);
+        } else if (this.size >= MUTEX_MAX_ENTRIES) {
+          const oldest = this.keys().next().value;
+          if (oldest !== void 0) super.delete(oldest);
+        }
+        return super.set(key, value);
+      }
+    };
+    refreshMutex = new LruMutexMap();
   }
-};
-var refreshMutex = new LruMutexMap();
+});
+
+// src/proxy/fetch-error.ts
+function formatFetchErrorForLog(err, url) {
+  if (err instanceof Error) {
+    const code = err.code;
+    const parts = [];
+    if (code) parts.push(code);
+    parts.push(err.message);
+    parts.push(`url=${url}`);
+    return parts.join(" ");
+  }
+  return `${String(err)} url=${url}`;
+}
+var init_fetch_error = __esm({
+  "src/proxy/fetch-error.ts"() {
+    "use strict";
+  }
+});
 
 // src/proxy/streaming.ts
-var TIMEOUT_CODES2 = /* @__PURE__ */ new Set(["ETIMEDOUT", "TIMEOUT", "UND_ERR_HEADERS_TIMEOUT"]);
-var HTTP_BAD_GATEWAY = 502;
 function parseRetryAfter(header) {
   if (!header) return void 0;
   const trimmed = header.trim();
@@ -198,21 +223,6 @@ function parseRetryAfter(header) {
   }
   return void 0;
 }
-var HOP_BY_HOP = /* @__PURE__ */ new Set([
-  "connection",
-  "keep-alive",
-  "proxy-authenticate",
-  "proxy-authorization",
-  "te",
-  "trailer",
-  "transfer-encoding",
-  "upgrade"
-]);
-var STRIP_HEADERS = /* @__PURE__ */ new Set([
-  ...HOP_BY_HOP,
-  "content-encoding",
-  "content-length"
-]);
 function stripSkalpelHeaders(headers) {
   const cleaned = { ...headers };
   delete cleaned["X-Skalpel-API-Key"];
@@ -230,29 +240,35 @@ async function handleStreamingRequest(_req, res, _config, _source, body, skalpel
   let fetchError = null;
   let usedFallback = false;
   if (useSkalpel) {
+    logger.info(`streaming fetch sending url=${skalpelUrl}`);
     try {
       response = await doStreamingFetch(skalpelUrl, body, forwardHeaders);
     } catch (err) {
       fetchError = err;
     }
+    if (response && !fetchError) logger.info(`streaming fetch received status=${response.status} url=${skalpelUrl}`);
     if (await isSkalpelBackendFailure(response, fetchError, logger)) {
-      logger.warn(`streaming: Skalpel backend failed (${fetchError ? fetchError.message : `status ${response?.status}`}), falling back to direct Anthropic API`);
+      logger.warn(`streaming: Skalpel backend failed (${fetchError ? formatFetchErrorForLog(fetchError, skalpelUrl) : `status ${response?.status}`}), falling back to direct Anthropic API`);
       usedFallback = true;
       response = null;
       fetchError = null;
       const directHeaders = stripSkalpelHeaders(forwardHeaders);
+      logger.info(`streaming fetch sending url=${directUrl} fallback=true`);
       try {
         response = await doStreamingFetch(directUrl, body, directHeaders);
       } catch (err) {
         fetchError = err;
       }
+      if (response && !fetchError) logger.info(`streaming fetch received status=${response.status} url=${directUrl} fallback=true`);
     }
   } else {
+    logger.info(`streaming fetch sending url=${directUrl}`);
     try {
       response = await doStreamingFetch(directUrl, body, forwardHeaders);
     } catch (err) {
       fetchError = err;
     }
+    if (response && !fetchError) logger.info(`streaming fetch received status=${response.status} url=${directUrl}`);
   }
   const finalUrl = usedFallback || !useSkalpel ? directUrl : skalpelUrl;
   const finalHeaders = usedFallback ? stripSkalpelHeaders(forwardHeaders) : forwardHeaders;
@@ -279,7 +295,7 @@ async function handleStreamingRequest(_req, res, _config, _source, body, skalpel
     );
   }
   if (!response || fetchError) {
-    const errMsg = fetchError ? fetchError.message : "no response from upstream";
+    const errMsg = fetchError ? formatFetchErrorForLog(fetchError, finalUrl) : "no response from upstream";
     logger.error(`streaming fetch failed: ${errMsg}`);
     res.writeHead(HTTP_BAD_GATEWAY, {
       "Content-Type": "text/event-stream",
@@ -352,12 +368,19 @@ data: ${JSON.stringify({ error: "no response body" })}
   try {
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
+    let chunkCount = 0;
+    let totalBytes = 0;
+    logger.info("streaming started");
     while (true) {
       const { done, value } = await reader.read();
       if (done) break;
+      chunkCount++;
+      totalBytes += value.byteLength;
+      logger.debug(`streaming chunk #${chunkCount} bytes=${value.byteLength} totalBytes=${totalBytes}`);
       const chunk = decoder.decode(value, { stream: true });
       res.write(chunk);
     }
+    logger.info(`streaming completed chunks=${chunkCount} totalBytes=${totalBytes}`);
   } catch (err) {
     logger.error(`streaming error: ${err.message}`);
     const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
@@ -375,11 +398,165 @@ data: ${JSON.stringify(envelope)}
   }
   res.end();
 }
+var TIMEOUT_CODES2, HTTP_BAD_GATEWAY, HOP_BY_HOP, STRIP_HEADERS;
+var init_streaming = __esm({
+  "src/proxy/streaming.ts"() {
+    "use strict";
+    init_dispatcher();
+    init_handler();
+    init_envelope();
+    init_recovery();
+    init_fetch_error();
+    TIMEOUT_CODES2 = /* @__PURE__ */ new Set(["ETIMEDOUT", "TIMEOUT", "UND_ERR_HEADERS_TIMEOUT"]);
+    HTTP_BAD_GATEWAY = 502;
+    HOP_BY_HOP = /* @__PURE__ */ new Set([
+      "connection",
+      "keep-alive",
+      "proxy-authenticate",
+      "proxy-authorization",
+      "te",
+      "trailer",
+      "transfer-encoding",
+      "upgrade"
+    ]);
+    STRIP_HEADERS = /* @__PURE__ */ new Set([
+      ...HOP_BY_HOP,
+      "content-encoding",
+      "content-length"
+    ]);
+  }
+});
+
+// src/proxy/ws-client.ts
+function defaultBackoffBaseMs() {
+  const raw = process.env.SKALPEL_WS_BACKOFF_BASE_MS;
+  const parsed = raw === void 0 ? NaN : parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 1e3;
+}
+function computeBackoff(attempt, baseMs) {
+  const exp = Math.min(MAX_BACKOFF_MS, baseMs * Math.pow(2, attempt));
+  const jitter = exp * (0.2 * (Math.random() * 2 - 1));
+  return Math.max(0, Math.floor(exp + jitter));
+}
+var import_node_events, import_ws, WS_SUBPROTOCOL, MAX_RECONNECTS, MAX_BACKOFF_MS, NON_TRANSIENT_CLOSE_CODES, BackendWsClient;
+var init_ws_client = __esm({
+  "src/proxy/ws-client.ts"() {
+    "use strict";
+    import_node_events = require("events");
+    import_ws = __toESM(require("ws"), 1);
+    WS_SUBPROTOCOL = "skalpel-codex-v1";
+    MAX_RECONNECTS = 5;
+    MAX_BACKOFF_MS = 6e4;
+    NON_TRANSIENT_CLOSE_CODES = /* @__PURE__ */ new Set([4e3, 4001, 4002, 4004]);
+    BackendWsClient = class extends import_node_events.EventEmitter {
+      opts;
+      ws = null;
+      reconnectAttempts = 0;
+      closedByUser = false;
+      pendingReconnect = null;
+      constructor(opts) {
+        super();
+        this.opts = opts;
+      }
+      async connect() {
+        return new Promise((resolve, reject) => {
+          const ws = new import_ws.default(this.opts.url, [WS_SUBPROTOCOL], {
+            headers: {
+              "X-Skalpel-API-Key": this.opts.apiKey,
+              Authorization: `Bearer ${this.opts.oauthToken}`,
+              "x-skalpel-source": this.opts.source
+            }
+          });
+          this.ws = ws;
+          ws.once("open", () => {
+            this.emit("open");
+            resolve();
+          });
+          ws.on("message", (data) => {
+            const text = data.toString("utf-8");
+            let parsed = null;
+            try {
+              parsed = JSON.parse(text);
+            } catch {
+              this.emit("error", new Error(`invalid frame: ${text.slice(0, 100)}`));
+              return;
+            }
+            this.emit("frame", parsed);
+          });
+          ws.on("error", (err) => {
+            this.opts.logger.debug(`ws-client error: ${err.message}`);
+            this.emit("error", err);
+          });
+          ws.once("close", (code, reasonBuf) => {
+            const reason = reasonBuf.toString("utf-8");
+            this.opts.logger.info(`ws-client close code=${code} reason=${reason}`);
+            this.ws = null;
+            if (this.closedByUser || code === 1e3) {
+              this.emit("close", code, reason);
+              return;
+            }
+            if (NON_TRANSIENT_CLOSE_CODES.has(code)) {
+              this.emit("close", code, reason);
+              this.emit("fallback", `close_${code}:${reason}`);
+              return;
+            }
+            this.scheduleReconnect(resolve, reject);
+            this.emit("close", code, reason);
+          });
+        });
+      }
+      scheduleReconnect(initialResolve, initialReject) {
+        if (this.reconnectAttempts >= MAX_RECONNECTS) {
+          this.emit("fallback", "reconnect_exhausted");
+          return;
+        }
+        this.reconnectAttempts += 1;
+        const delay = computeBackoff(this.reconnectAttempts, defaultBackoffBaseMs());
+        this.opts.logger.info(
+          `ws-client reconnect attempt=${this.reconnectAttempts} delay=${delay}ms`
+        );
+        this.pendingReconnect = setTimeout(() => {
+          this.pendingReconnect = null;
+          this.connect().catch((err) => {
+            this.opts.logger.debug(`reconnect failed: ${err.message}`);
+          });
+        }, delay);
+        void initialResolve;
+        void initialReject;
+      }
+      send(frame) {
+        if (this.ws === null || this.ws.readyState !== import_ws.default.OPEN) {
+          throw new Error("ws-client send: socket not open");
+        }
+        this.ws.send(JSON.stringify(frame));
+      }
+      close(code = 1e3, reason = "client close") {
+        this.closedByUser = true;
+        if (this.pendingReconnect !== null) {
+          clearTimeout(this.pendingReconnect);
+          this.pendingReconnect = null;
+        }
+        if (this.ws !== null) {
+          try {
+            this.ws.close(code, reason);
+          } catch {
+          }
+          this.ws = null;
+        }
+      }
+    };
+  }
+});
 
 // src/proxy/handler.ts
-var TIMEOUT_CODES3 = /* @__PURE__ */ new Set(["ETIMEDOUT", "TIMEOUT", "UND_ERR_HEADERS_TIMEOUT"]);
-var HTTP_BAD_GATEWAY2 = 502;
-var SKALPEL_EXACT_PATHS = /* @__PURE__ */ new Set(["/v1/messages"]);
+var handler_exports = {};
+__export(handler_exports, {
+  buildForwardHeaders: () => buildForwardHeaders,
+  handleRequest: () => handleRequest,
+  handleWebSocketBridge: () => handleWebSocketBridge,
+  isSkalpelBackendFailure: () => isSkalpelBackendFailure,
+  shouldRouteToSkalpel: () => shouldRouteToSkalpel
+});
 function collectBody(req) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -423,17 +600,6 @@ async function isSkalpelBackendFailure(response, err, logger) {
     return true;
   }
 }
-var FORWARD_HEADER_STRIP = /* @__PURE__ */ new Set([
-  "host",
-  "connection",
-  "keep-alive",
-  "proxy-authenticate",
-  "proxy-authorization",
-  "te",
-  "trailer",
-  "transfer-encoding",
-  "upgrade"
-]);
 function buildForwardHeaders(req, config, source, useSkalpel) {
   const forwardHeaders = {};
   for (const [key, value] of Object.entries(req.headers)) {
@@ -469,18 +635,6 @@ function stripSkalpelHeaders2(headers) {
   delete cleaned["X-Skalpel-Auth-Mode"];
   return cleaned;
 }
-var STRIP_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
-  "connection",
-  "keep-alive",
-  "proxy-authenticate",
-  "proxy-authorization",
-  "te",
-  "trailer",
-  "transfer-encoding",
-  "upgrade",
-  "content-encoding",
-  "content-length"
-]);
 function extractResponseHeaders(response) {
   const headers = {};
   for (const [key, value] of response.headers.entries()) {
@@ -498,11 +652,22 @@ async function handleRequest(req, res, config, source, logger) {
     typeof req.headers.authorization === "string" ? req.headers.authorization : void 0
   );
   logger.info(`${source} ${method} ${path4} token=${fp}`);
+  if (source === "codex") {
+    const ua = req.headers["user-agent"] ?? "";
+    const authScheme = typeof req.headers.authorization === "string" ? req.headers.authorization.split(" ")[0] ?? "none" : "none";
+    const upgrade = req.headers.upgrade ?? "";
+    const connection = req.headers.connection ?? "";
+    const contentType = req.headers["content-type"] ?? "";
+    logger.debug(`codex-diag method=${method} path=${path4} ua=${ua} authScheme=${authScheme} upgrade=${upgrade} connection=${connection} contentType=${contentType} hasBody=${method !== "GET" && method !== "HEAD"}`);
+  }
   let response = null;
   try {
     const body = await collectBody(req);
+    logger.info(`body collected bytes=${body.length}`);
     const useSkalpel = shouldRouteToSkalpel(path4, source);
+    logger.info(`routing useSkalpel=${useSkalpel}`);
     const forwardHeaders = buildForwardHeaders(req, config, source, useSkalpel);
+    logger.debug(`headers built skalpelHeaders=${useSkalpel} authConverted=${!forwardHeaders["authorization"] && !!forwardHeaders["x-api-key"]}`);
     let isStreaming = false;
     if (body) {
       try {
@@ -511,6 +676,7 @@ async function handleRequest(req, res, config, source, logger) {
       } catch {
       }
     }
+    logger.info(`stream detection isStreaming=${isStreaming}`);
     if (isStreaming) {
       const skalpelUrl2 = `${config.remoteBaseUrl}${path4}`;
       const directUrl2 = source === "claude-code" ? `${config.anthropicDirectUrl}${path4}` : source === "cursor" ? `${config.cursorDirectUrl}${path4}` : `${config.openaiDirectUrl}${path4}`;
@@ -524,35 +690,42 @@ async function handleRequest(req, res, config, source, logger) {
     let fetchError = null;
     let usedFallback = false;
     if (useSkalpel) {
+      logger.info(`fetch sending url=${skalpelUrl} method=${method}`);
       try {
         response = await fetch(skalpelUrl, { method, headers: forwardHeaders, body: fetchBody, dispatcher: skalpelDispatcher });
       } catch (err) {
         fetchError = err;
       }
+      if (response && !fetchError) logger.info(`fetch received status=${response.status} url=${skalpelUrl}`);
       if (await isSkalpelBackendFailure(response, fetchError, logger)) {
-        logger.warn(`${method} ${path4} Skalpel backend failed (${fetchError ? fetchError.message : `status ${response?.status}`}), falling back to direct Anthropic API`);
+        logger.warn(`${method} ${path4} Skalpel backend failed (${fetchError ? formatFetchErrorForLog(fetchError, skalpelUrl) : `status ${response?.status}`}), falling back to direct Anthropic API`);
         usedFallback = true;
         response = null;
         fetchError = null;
         const directHeaders = stripSkalpelHeaders2(forwardHeaders);
+        logger.info(`fetch sending url=${directUrl} method=${method} fallback=true`);
         try {
           response = await fetch(directUrl, { method, headers: directHeaders, body: fetchBody, dispatcher: skalpelDispatcher });
         } catch (err) {
           fetchError = err;
         }
+        if (response && !fetchError) logger.info(`fetch received status=${response.status} url=${directUrl} fallback=true`);
       }
     } else {
+      logger.info(`fetch sending url=${directUrl} method=${method}`);
       try {
         response = await fetch(directUrl, { method, headers: forwardHeaders, body: fetchBody, dispatcher: skalpelDispatcher });
       } catch (err) {
         fetchError = err;
       }
+      if (response && !fetchError) logger.info(`fetch received status=${response.status} url=${directUrl}`);
     }
     const fetchUrl = usedFallback || !useSkalpel ? directUrl : skalpelUrl;
     const fetchHeaders = usedFallback ? stripSkalpelHeaders2(forwardHeaders) : forwardHeaders;
     if (fetchError) {
       const code = fetchError.code;
       if (code && TIMEOUT_CODES3.has(code)) {
+        logger.warn(`timeout detected code=${code} url=${fetchUrl}`);
         try {
           response = await handleTimeoutWithRetry(
             fetchError,
@@ -575,6 +748,7 @@ async function handleRequest(req, res, config, source, logger) {
       throw fetchError ?? new Error("no response from upstream");
     }
     if (response.status === 429) {
+      logger.info(`429 received url=${fetchUrl}`);
       response = await handle429WithRetryAfter(
         response,
         () => fetch(fetchUrl, {
@@ -601,11 +775,12 @@ async function handleRequest(req, res, config, source, logger) {
     const responseHeaders = extractResponseHeaders(response);
     const responseBody = Buffer.from(await response.arrayBuffer());
     responseHeaders["content-length"] = String(responseBody.length);
+    logger.info(`response forwarding status=${response.status} bodyBytes=${responseBody.length}`);
     res.writeHead(response.status, responseHeaders);
     res.end(responseBody);
     logger.info(`${method} ${path4} source=${source} status=${response.status}${usedFallback ? " (fallback)" : ""} latency=${Date.now() - start}ms`);
   } catch (err) {
-    logger.error(`${method} ${path4} source=${source} error=${err.message}`);
+    logger.error(`${method} ${path4} source=${source} error=${formatFetchErrorForLog(err, path4)}`);
     if (!res.headersSent) {
       if (response !== null) {
         const upstreamStatus = response.status;
@@ -629,9 +804,215 @@ async function handleRequest(req, res, config, source, logger) {
     }
   }
 }
+async function handleWebSocketBridge(clientWs, req, config, source, logger) {
+  const backendUrl = buildBackendWsUrl(config);
+  const oauthHeader = req.headers["authorization"] ?? "";
+  const oauthToken = oauthHeader.toLowerCase().startsWith("bearer ") ? oauthHeader.slice(7).trim() : "";
+  const backend = new BackendWsClient({
+    url: backendUrl,
+    apiKey: config.apiKey,
+    oauthToken,
+    source,
+    logger
+  });
+  let fallbackActive = false;
+  let backendOpen = false;
+  const pendingClientFrames = [];
+  const inflightRequests = /* @__PURE__ */ new Map();
+  const flushPending = () => {
+    if (!backendOpen || fallbackActive) return;
+    while (pendingClientFrames.length > 0) {
+      const frame = pendingClientFrames.shift();
+      if (frame === void 0) break;
+      try {
+        backend.send(frame);
+        if (frame.type === "request") {
+          const id = String(frame.id ?? "");
+          if (id) inflightRequests.set(id, frame);
+        }
+      } catch (err) {
+        logger.warn(`bridge: flush backend.send failed: ${err.message}`);
+        pendingClientFrames.unshift(frame);
+        return;
+      }
+    }
+  };
+  clientWs.on("message", (data) => {
+    const text = data.toString("utf-8");
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      logger.warn("bridge: invalid client frame (dropped)");
+      return;
+    }
+    pendingClientFrames.push(parsed);
+    flushPending();
+  });
+  clientWs.on("close", (code, reason) => {
+    logger.info(`bridge: client closed code=${code} reason=${String(reason)}`);
+    backend.close(1e3, "client closed");
+  });
+  backend.on("open", () => {
+    backendOpen = true;
+    flushPending();
+  });
+  backend.on("frame", (frame) => {
+    try {
+      clientWs.send(JSON.stringify(frame));
+    } catch (err) {
+      logger.debug(`bridge: client.send failed: ${err.message}`);
+    }
+    if (typeof frame === "object" && frame !== null) {
+      const fr = frame;
+      const t = fr.type;
+      if (t === "done" || t === "error") {
+        const id = String(fr.id ?? "");
+        if (id) inflightRequests.delete(id);
+      }
+    }
+  });
+  backend.on("close", (code, reason) => {
+    logger.info(`bridge: backend closed code=${code} reason=${reason}`);
+    backendOpen = false;
+  });
+  backend.on("error", (err) => {
+    logger.debug(`bridge: backend error: ${err.message}`);
+  });
+  backend.on("fallback", (reason) => {
+    fallbackActive = true;
+    backendOpen = false;
+    logger.warn(`bridge: backend fallback reason=${reason} \u2014 switching to HTTP POST`);
+    const replay = [
+      ...inflightRequests.values(),
+      ...pendingClientFrames.splice(0)
+    ];
+    inflightRequests.clear();
+    drainPendingToHttp(clientWs, config, source, logger, replay).catch((httpErr) => {
+      logger.error(`bridge HTTP drain failed: ${httpErr.message}`);
+      try {
+        clientWs.close(4003, "fallback drain failed");
+      } catch {
+      }
+    });
+  });
+  try {
+    await backend.connect();
+  } catch (err) {
+    logger.error(`bridge: initial connect failed: ${err.message}`);
+  }
+}
+function buildBackendWsUrl(config) {
+  const base = config.remoteBaseUrl.replace(/^http/, "ws");
+  return `${base}/v1/responses`;
+}
+async function drainPendingToHttp(clientWs, config, source, logger, frames) {
+  for (const frame of frames) {
+    if (frame.type !== "request") continue;
+    const payload = frame.payload ?? {};
+    const id = String(frame.id ?? "");
+    try {
+      const resp = await fetch(`${config.remoteBaseUrl}/v1/responses`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Skalpel-API-Key": config.apiKey,
+          "x-skalpel-source": source,
+          Accept: "text/event-stream"
+        },
+        body: JSON.stringify(payload)
+      });
+      if (!resp.ok || resp.body === null) {
+        clientWs.send(
+          JSON.stringify({
+            type: "error",
+            id,
+            payload: { code: resp.status, detail: `http fallback status ${resp.status}` }
+          })
+        );
+        continue;
+      }
+      const reader = resp.body.getReader();
+      const decoder = new TextDecoder("utf-8");
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value === void 0) continue;
+        const chunkText = decoder.decode(value, { stream: true });
+        clientWs.send(
+          JSON.stringify({ type: "chunk", id, payload: { data: chunkText } })
+        );
+      }
+      clientWs.send(JSON.stringify({ type: "done", id, payload: {} }));
+    } catch (err) {
+      logger.warn(`http fallback frame failed: ${err.message}`);
+      clientWs.send(
+        JSON.stringify({
+          type: "error",
+          id,
+          payload: { code: 502, detail: err.message }
+        })
+      );
+    }
+  }
+}
+var TIMEOUT_CODES3, HTTP_BAD_GATEWAY2, SKALPEL_EXACT_PATHS, FORWARD_HEADER_STRIP, STRIP_RESPONSE_HEADERS;
+var init_handler = __esm({
+  "src/proxy/handler.ts"() {
+    "use strict";
+    init_streaming();
+    init_dispatcher();
+    init_envelope();
+    init_ws_client();
+    init_recovery();
+    init_fetch_error();
+    TIMEOUT_CODES3 = /* @__PURE__ */ new Set(["ETIMEDOUT", "TIMEOUT", "UND_ERR_HEADERS_TIMEOUT"]);
+    HTTP_BAD_GATEWAY2 = 502;
+    SKALPEL_EXACT_PATHS = /* @__PURE__ */ new Set(["/v1/messages"]);
+    FORWARD_HEADER_STRIP = /* @__PURE__ */ new Set([
+      "host",
+      "connection",
+      "keep-alive",
+      "proxy-authenticate",
+      "proxy-authorization",
+      "te",
+      "trailer",
+      "transfer-encoding",
+      "upgrade"
+    ]);
+    STRIP_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
+      "connection",
+      "keep-alive",
+      "proxy-authenticate",
+      "proxy-authorization",
+      "te",
+      "trailer",
+      "transfer-encoding",
+      "upgrade",
+      "content-encoding",
+      "content-length"
+    ]);
+  }
+});
+
+// src/proxy/index.ts
+var proxy_exports = {};
+__export(proxy_exports, {
+  getProxyStatus: () => getProxyStatus,
+  loadConfig: () => loadConfig,
+  saveConfig: () => saveConfig,
+  startProxy: () => startProxy,
+  stopProxy: () => stopProxy
+});
+module.exports = __toCommonJS(proxy_exports);
+
+// src/proxy/server.ts
+var import_node_http = __toESM(require("http"), 1);
+init_handler();
 
 // src/proxy/health.ts
-function handleHealthRequest(res, config, startTime) {
+function handleHealthRequest(res, config, startTime, logger) {
+  logger?.debug("health check served");
   const body = JSON.stringify({
     status: "ok",
     uptime: Date.now() - startTime,
@@ -725,6 +1106,20 @@ function removePid(pidFile) {
   }
 }
 
+// src/proxy/health-check.ts
+async function isProxyAlive(port, timeoutMs = 2e3) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`http://localhost:${port}/health`, { signal: controller.signal });
+    return res.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/proxy/logger.ts
 var import_node_fs2 = __toESM(require("fs"), 1);
 var import_node_path2 = __toESM(require("path"), 1);
@@ -791,6 +1186,67 @@ var Logger = class _Logger {
   }
 };
 
+// src/proxy/ws-server.ts
+var import_ws2 = require("ws");
+var WS_SUBPROTOCOL2 = "skalpel-codex-v1";
+var wss = new import_ws2.WebSocketServer({ noServer: true });
+function reject426(socket, payload) {
+  const body = JSON.stringify(payload);
+  socket.write(
+    `HTTP/1.1 426 Upgrade Required\r
+Content-Type: application/json\r
+Content-Length: ${Buffer.byteLength(body)}\r
+Connection: close\r
+\r
+` + body
+  );
+  socket.destroy();
+}
+function handleCodexUpgrade(req, socket, head, config, logger) {
+  const wsFlag = process.env.SKALPEL_CODEX_WS ?? "1";
+  if (wsFlag === "0") {
+    logger.warn("ws-upgrade rejected: feature flag SKALPEL_CODEX_WS=0");
+    reject426(socket, { error: "ws_disabled" });
+    return;
+  }
+  const offered = req.headers["sec-websocket-protocol"] ?? "";
+  const tokens = offered.split(",").map((t) => t.trim()).filter(Boolean);
+  if (!tokens.includes(WS_SUBPROTOCOL2)) {
+    logger.warn(`ws-upgrade rejected: unsupported subprotocol offered="${offered}"`);
+    reject426(socket, { error: "unsupported_subprotocol" });
+    return;
+  }
+  wss.handleUpgrade(req, socket, head, (clientWs) => {
+    logger.info(`ws-upgrade accepted path=${req.url ?? ""} subproto=${WS_SUBPROTOCOL2}`);
+    Promise.resolve().then(() => (init_handler(), handler_exports)).then((mod) => {
+      const bridge = mod.handleWebSocketBridge;
+      if (typeof bridge !== "function") {
+        clientWs.send(
+          JSON.stringify({
+            type: "error",
+            payload: { code: "not_implemented" }
+          })
+        );
+        clientWs.close(4003, "bridge pending");
+        return;
+      }
+      void bridge(clientWs, req, config, "codex", logger);
+    }).catch((err) => {
+      logger.error(`ws bridge import failed: ${err?.message ?? String(err)}`);
+      try {
+        clientWs.send(
+          JSON.stringify({
+            type: "error",
+            payload: { code: "bridge_import_failed" }
+          })
+        );
+      } catch {
+      }
+      clientWs.close(4003, "bridge import failed");
+    });
+  });
+}
+
 // src/proxy/server.ts
 var proxyStartTime = 0;
 var connCounter = 0;
@@ -807,7 +1263,7 @@ function startProxy(config) {
   proxyStartTime = Date.now();
   const anthropicServer = import_node_http.default.createServer((req, res) => {
     if (req.url === "/health" && req.method === "GET") {
-      handleHealthRequest(res, config, startTime);
+      handleHealthRequest(res, config, startTime, logger.child("health"));
       return;
     }
     const connId = computeConnId(req);
@@ -815,7 +1271,7 @@ function startProxy(config) {
   });
   const openaiServer = import_node_http.default.createServer((req, res) => {
     if (req.url === "/health" && req.method === "GET") {
-      handleHealthRequest(res, config, startTime);
+      handleHealthRequest(res, config, startTime, logger.child("health"));
       return;
     }
     const connId = computeConnId(req);
@@ -823,12 +1279,71 @@ function startProxy(config) {
   });
   const cursorServer = import_node_http.default.createServer((req, res) => {
     if (req.url === "/health" && req.method === "GET") {
-      handleHealthRequest(res, config, startTime);
+      handleHealthRequest(res, config, startTime, logger.child("health"));
       return;
     }
     const connId = computeConnId(req);
     handleRequest(req, res, config, "cursor", logger.child(connId));
   });
+  anthropicServer.on("upgrade", (req, socket, _head) => {
+    const ua = req.headers["user-agent"] ?? "";
+    logger.warn(`upgrade-attempt port=${config.anthropicPort} method=${req.method} url=${req.url} ua=${ua} origin=${req.headers.origin ?? ""}`);
+    const body = JSON.stringify({
+      error: "upgrade_required",
+      message: "Skalpel proxy is HTTP-only",
+      hint: 'Use wire_api="responses" over HTTP in your Codex config. See docs/codex-integration-fix.md.'
+    });
+    socket.write(
+      `HTTP/1.1 426 Upgrade Required\r
+Content-Type: application/json\r
+Content-Length: ${Buffer.byteLength(body)}\r
+Connection: close\r
+\r
+` + body
+    );
+    socket.destroy();
+  });
+  openaiServer.on("upgrade", (req, socket, head) => {
+    const ua = req.headers["user-agent"] ?? "";
+    logger.warn(`upgrade-attempt port=${config.openaiPort} method=${req.method} url=${req.url} ua=${ua} origin=${req.headers.origin ?? ""}`);
+    const pathname = (req.url ?? "").split("?")[0];
+    if (pathname === "/v1/responses") {
+      handleCodexUpgrade(req, socket, head, config, logger);
+      return;
+    }
+    const body = JSON.stringify({
+      error: "upgrade_required",
+      message: "Skalpel proxy is HTTP-only",
+      hint: 'Use wire_api="responses" over HTTP in your Codex config. See docs/codex-integration-fix.md.'
+    });
+    socket.write(
+      `HTTP/1.1 426 Upgrade Required\r
+Content-Type: application/json\r
+Content-Length: ${Buffer.byteLength(body)}\r
+Connection: close\r
+\r
+` + body
+    );
+    socket.destroy();
+  });
+  cursorServer.on("upgrade", (req, socket, _head) => {
+    const ua = req.headers["user-agent"] ?? "";
+    logger.warn(`upgrade-attempt port=${config.cursorPort} method=${req.method} url=${req.url} ua=${ua} origin=${req.headers.origin ?? ""}`);
+    const body = JSON.stringify({
+      error: "upgrade_required",
+      message: "Skalpel proxy is HTTP-only",
+      hint: 'Use wire_api="responses" over HTTP in your Codex config. See docs/codex-integration-fix.md.'
+    });
+    socket.write(
+      `HTTP/1.1 426 Upgrade Required\r
+Content-Type: application/json\r
+Content-Length: ${Buffer.byteLength(body)}\r
+Connection: close\r
+\r
+` + body
+    );
+    socket.destroy();
+  });
   anthropicServer.on("error", (err) => {
     if (err.code === "EADDRINUSE") {
       logger.error(`Port ${config.anthropicPort} is already in use. Another Skalpel proxy or process may be running.`);
@@ -856,17 +1371,26 @@ function startProxy(config) {
     removePid(config.pidFile);
     process.exit(1);
   });
+  let bound = 0;
+  const onBound = () => {
+    bound++;
+    if (bound === 3) {
+      writePid(config.pidFile);
+      logger.info(`Proxy started (pid=${process.pid}) ports=${config.anthropicPort},${config.openaiPort},${config.cursorPort}`);
+    }
+  };
   anthropicServer.listen(config.anthropicPort, () => {
     logger.info(`Anthropic proxy listening on port ${config.anthropicPort}`);
+    onBound();
   });
   openaiServer.listen(config.openaiPort, () => {
     logger.info(`OpenAI proxy listening on port ${config.openaiPort}`);
+    onBound();
   });
   cursorServer.listen(config.cursorPort, () => {
     logger.info(`Cursor proxy listening on port ${config.cursorPort}`);
+    onBound();
   });
-  writePid(config.pidFile);
-  logger.info(`Proxy started (pid=${process.pid}) ports=${config.anthropicPort},${config.openaiPort},${config.cursorPort}`);
   const cleanup = () => {
     logger.info("Shutting down proxy...");
     anthropicServer.close();
@@ -899,12 +1423,23 @@ function stopProxy(config) {
   removePid(config.pidFile);
   return true;
 }
-function getProxyStatus(config) {
+async function getProxyStatus(config) {
   const pid = readPid(config.pidFile);
+  if (pid !== null) {
+    return {
+      running: true,
+      pid,
+      uptime: proxyStartTime > 0 ? Date.now() - proxyStartTime : 0,
+      anthropicPort: config.anthropicPort,
+      openaiPort: config.openaiPort,
+      cursorPort: config.cursorPort
+    };
+  }
+  const alive = await isProxyAlive(config.anthropicPort);
   return {
-    running: pid !== null,
-    pid,
-    uptime: proxyStartTime > 0 ? Date.now() - proxyStartTime : 0,
+    running: alive,
+    pid: null,
+    uptime: 0,
     anthropicPort: config.anthropicPort,
     openaiPort: config.openaiPort,
     cursorPort: config.cursorPort