skalpel 2.0.11 → 2.0.13

package/dist/index.js

@@ -56,8 +56,36 @@ var SkalpelUnavailableError = class extends SkalpelError {
     this.name = "SkalpelUnavailableError";
   }
 };
+var SkalpelClientRequestError = class extends SkalpelError {
+  constructor(message, statusCode) {
+    super(message, "SKALPEL_CLIENT_REQUEST", statusCode);
+    this.name = "SkalpelClientRequestError";
+  }
+};
 
 // src/fallback.ts
+var TRULY_CLIENT_4XX = /* @__PURE__ */ new Set([
+  400,
+  403,
+  404,
+  405,
+  409,
+  410,
+  411,
+  413,
+  415,
+  417,
+  418,
+  421,
+  422,
+  423,
+  424,
+  425,
+  426,
+  428,
+  431,
+  451
+]);
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -73,12 +101,21 @@ function classifyError(err) {
     const retryAfter = error.headers?.["retry-after"] ? parseInt(error.headers["retry-after"], 10) : void 0;
     return new SkalpelRateLimitError(message, retryAfter);
   }
+  if (status === 408) {
+    return new SkalpelTimeoutError(message);
+  }
   if (error.code === "ETIMEDOUT" || error.code === "TIMEOUT" || error.code === "UND_ERR_HEADERS_TIMEOUT") {
     return new SkalpelTimeoutError(message);
   }
   if (status && status >= 500) {
     return new SkalpelUnavailableError(message, status);
   }
+  if (status && TRULY_CLIENT_4XX.has(status)) {
+    return new SkalpelClientRequestError(message, status);
+  }
+  if (status && status >= 400 && status < 500) {
+    return new SkalpelClientRequestError(message, status);
+  }
   return new SkalpelUnavailableError(message, status);
 }
 async function withFallback(primaryFn, fallbackFn, options = {}) {
@@ -92,6 +129,9 @@ async function withFallback(primaryFn, fallbackFn, options = {}) {
       if (lastError instanceof SkalpelAuthError) {
         throw lastError;
       }
+      if (lastError instanceof SkalpelClientRequestError) {
+        throw lastError;
+      }
       if (lastError instanceof SkalpelRateLimitError && lastError.retryAfter && attempt < retries) {
         await sleep(lastError.retryAfter * 1e3);
         continue;
@@ -118,6 +158,21 @@ async function withFallback(primaryFn, fallbackFn, options = {}) {
 var VERSION = "1.0.5";
 
 // src/client.ts
+var AsyncMutex = class {
+  locked = false;
+  queue = [];
+  async acquire() {
+    if (this.locked) {
+      await new Promise((resolve) => this.queue.push(resolve));
+    }
+    this.locked = true;
+    return () => {
+      this.locked = false;
+      const next = this.queue.shift();
+      if (next) next();
+    };
+  }
+};
 function resolveConfig(options) {
   return {
     apiKey: options.apiKey,
@@ -184,29 +239,33 @@ function wrapOpenAI(client, config) {
   const c = client;
   const skalpelHeaders = buildSkalpelHeaders(config);
   const originalBaseURL = c.baseURL;
+  const mutex = new AsyncMutex();
   function createMethodProxy(target, methodName) {
     const originalMethod = target[methodName];
     return async function(...args) {
       const primaryFn = async () => {
-        c.baseURL = `${config.baseURL}/v1`;
-        const requestArgs = args[0];
-        const extraHeaders = skalpelHeaders;
-        let callArgs;
-        if (args.length >= 2 && typeof args[1] === "object" && args[1] !== null) {
-          const opts = args[1];
-          opts.headers = { ...extraHeaders, ...opts.headers };
-          callArgs = [requestArgs, opts, ...args.slice(2)];
-        } else {
-          callArgs = [requestArgs, { headers: extraHeaders }, ...args.slice(2)];
-        }
+        const release = await mutex.acquire();
         try {
-          const result = await originalMethod.apply(target, callArgs);
-          extractMetadataFromResponse(result, config);
-          c.baseURL = originalBaseURL;
-          return result;
-        } catch (err) {
-          c.baseURL = originalBaseURL;
-          throw err;
+          c.baseURL = `${config.baseURL}/v1`;
+          const requestArgs = args[0];
+          const extraHeaders = skalpelHeaders;
+          let callArgs;
+          if (args.length >= 2 && typeof args[1] === "object" && args[1] !== null) {
+            const opts = args[1];
+            opts.headers = { ...extraHeaders, ...opts.headers };
+            callArgs = [requestArgs, opts, ...args.slice(2)];
+          } else {
+            callArgs = [requestArgs, { headers: extraHeaders }, ...args.slice(2)];
+          }
+          try {
+            const result = await originalMethod.apply(target, callArgs);
+            extractMetadataFromResponse(result, config);
+            return result;
+          } finally {
+            c.baseURL = originalBaseURL;
+          }
+        } finally {
+          release();
         }
       };
       const fallbackFn = async () => {
@@ -250,33 +309,36 @@ function wrapAnthropic(client, config) {
   const c = client;
   const skalpelHeaders = buildSkalpelHeaders(config);
   const originalBaseURL = c.baseURL ?? c._client?.baseURL;
+  const mutex = new AsyncMutex();
   function createMethodProxy(target, methodName) {
     const originalMethod = target[methodName];
     return async function(...args) {
       const primaryFn = async () => {
-        const proxyURL = config.baseURL;
-        if ("baseURL" in c) c.baseURL = proxyURL;
-        if (c._client && "baseURL" in c._client) c._client.baseURL = proxyURL;
-        const requestArgs = args[0];
-        const extraHeaders = skalpelHeaders;
-        let callArgs;
-        if (args.length >= 2 && typeof args[1] === "object" && args[1] !== null) {
-          const opts = args[1];
-          opts.headers = { ...extraHeaders, ...opts.headers };
-          callArgs = [requestArgs, opts, ...args.slice(2)];
-        } else {
-          callArgs = [requestArgs, { headers: extraHeaders }, ...args.slice(2)];
-        }
+        const release = await mutex.acquire();
         try {
-          const result = await originalMethod.apply(target, callArgs);
-          extractMetadataFromResponse(result, config);
-          if ("baseURL" in c) c.baseURL = originalBaseURL;
-          if (c._client && "baseURL" in c._client) c._client.baseURL = originalBaseURL;
-          return result;
-        } catch (err) {
-          if ("baseURL" in c) c.baseURL = originalBaseURL;
-          if (c._client && "baseURL" in c._client) c._client.baseURL = originalBaseURL;
-          throw err;
+          const proxyURL = config.baseURL;
+          if ("baseURL" in c) c.baseURL = proxyURL;
+          if (c._client && "baseURL" in c._client) c._client.baseURL = proxyURL;
+          const requestArgs = args[0];
+          const extraHeaders = skalpelHeaders;
+          let callArgs;
+          if (args.length >= 2 && typeof args[1] === "object" && args[1] !== null) {
+            const opts = args[1];
+            opts.headers = { ...extraHeaders, ...opts.headers };
+            callArgs = [requestArgs, opts, ...args.slice(2)];
+          } else {
+            callArgs = [requestArgs, { headers: extraHeaders }, ...args.slice(2)];
+          }
+          try {
+            const result = await originalMethod.apply(target, callArgs);
+            extractMetadataFromResponse(result, config);
+            return result;
+          } finally {
+            if ("baseURL" in c) c.baseURL = originalBaseURL;
+            if (c._client && "baseURL" in c._client) c._client.baseURL = originalBaseURL;
+          }
+        } finally {
+          release();
         }
       };
       const fallbackFn = async () => {
@@ -338,7 +400,11 @@ async function contextRequest(config, path4, body) {
     });
     if (!response.ok) {
       const text = await response.text().catch(() => "");
-      throw new Error(`Skalpel context API error ${response.status}: ${text}`);
+      const message = `Skalpel context API error ${response.status}: ${text}`;
+      if (response.status >= 400 && response.status < 500) {
+        throw new SkalpelClientRequestError(message, response.status);
+      }
+      throw new SkalpelUnavailableError(message, response.status);
     }
     return await response.json();
   } finally {
@@ -417,6 +483,7 @@ async function resolveContext(options, params) {
 }
 
 // src/url-swap.ts
+var SKALPEL_MANAGED_SENTINEL = "skalpel-managed";
 function buildHeaders(options) {
   const headers = {
     "X-Skalpel-SDK-Version": VERSION,
@@ -430,10 +497,14 @@ function buildHeaders(options) {
 async function createSkalpelOpenAI(options) {
   const { default: OpenAI } = await import("openai");
   const baseURL = `${options.baseURL ?? "https://api.skalpel.ai"}/v1`;
+  const sdkApiKey = options.providerApiKey ? options.providerApiKey : SKALPEL_MANAGED_SENTINEL;
   return new OpenAI({
     baseURL,
-    apiKey: options.apiKey,
-    defaultHeaders: buildHeaders(options),
+    apiKey: sdkApiKey,
+    defaultHeaders: {
+      ...buildHeaders(options),
+      "Authorization": `Bearer ${options.apiKey}`
+    },
     timeout: options.timeout ?? 3e4,
     maxRetries: options.retries ?? 2
   });
@@ -441,9 +512,10 @@ async function createSkalpelOpenAI(options) {
 async function createSkalpelAnthropic(options) {
   const { default: Anthropic } = await import("@anthropic-ai/sdk");
   const baseURL = options.baseURL ?? "https://api.skalpel.ai";
+  const sdkApiKey = options.providerApiKey ? options.providerApiKey : SKALPEL_MANAGED_SENTINEL;
   return new Anthropic({
     baseURL,
-    apiKey: options.providerApiKey ?? options.apiKey,
+    apiKey: sdkApiKey,
     defaultHeaders: {
       ...buildHeaders(options),
       "Authorization": `Bearer ${options.apiKey}`
@@ -456,7 +528,163 @@ async function createSkalpelAnthropic(options) {
 // src/proxy/server.ts
 import http from "http";
 
+// src/proxy/dispatcher.ts
+import { Agent } from "undici";
+var skalpelDispatcher = new Agent({
+  keepAliveTimeout: 1e4,
+  keepAliveMaxTimeout: 6e4,
+  connections: 100,
+  pipelining: 1
+});
+
+// src/proxy/envelope.ts
+function isAnthropicShaped(body) {
+  if (typeof body !== "object" || body === null) return false;
+  const b = body;
+  if (b.type !== "error") return false;
+  if (typeof b.error !== "object" || b.error === null) return false;
+  return true;
+}
+function defaultErrorTypeFor(status) {
+  if (status === 400) return "invalid_request_error";
+  if (status === 401 || status === 403) return "authentication_error";
+  if (status === 404) return "not_found_error";
+  if (status === 408) return "timeout_error";
+  if (status === 429) return "rate_limit_error";
+  if (status >= 500) return "api_error";
+  if (status >= 400) return "invalid_request_error";
+  return "api_error";
+}
+function buildErrorEnvelope(status, upstreamBody, origin, hint, retryAfter) {
+  let parsed = upstreamBody;
+  if (typeof upstreamBody === "string" && upstreamBody.length > 0) {
+    try {
+      parsed = JSON.parse(upstreamBody);
+    } catch {
+      parsed = upstreamBody;
+    }
+  }
+  let type = defaultErrorTypeFor(status);
+  let message;
+  if (isAnthropicShaped(parsed)) {
+    const inner = parsed.error;
+    if (typeof inner.type === "string" && inner.type.length > 0) {
+      type = inner.type;
+    }
+    message = typeof inner.message === "string" && inner.message.length > 0 ? inner.message : defaultMessageForStatus(status);
+  } else if (typeof parsed === "string" && parsed.length > 0) {
+    message = parsed;
+  } else {
+    message = defaultMessageForStatus(status);
+  }
+  const envelope = {
+    type: "error",
+    error: {
+      type,
+      message,
+      status_code: status,
+      origin
+    }
+  };
+  if (hint !== void 0) envelope.error.hint = hint;
+  if (retryAfter !== void 0) envelope.error.retry_after = retryAfter;
+  return envelope;
+}
+function defaultMessageForStatus(status) {
+  if (status === 401) return "Authentication failed";
+  if (status === 403) return "Forbidden";
+  if (status === 404) return "Not found";
+  if (status === 408) return "Request timed out";
+  if (status === 429) return "Rate limit exceeded";
+  if (status === 502) return "Bad gateway";
+  if (status === 503) return "Service unavailable";
+  if (status === 504) return "Gateway timeout";
+  if (status >= 500) return "Upstream error";
+  if (status >= 400) return "Client error";
+  return "Error";
+}
+
+// src/proxy/recovery.ts
+import { createHash } from "crypto";
+function parseRetryAfterHeader(header) {
+  if (!header) return void 0;
+  const trimmed = header.trim();
+  if (!trimmed) return void 0;
+  const n = Number(trimmed);
+  if (Number.isFinite(n) && n >= 0) return Math.floor(n);
+  const dateMs = Date.parse(trimmed);
+  if (Number.isFinite(dateMs)) {
+    return Math.max(0, Math.ceil((dateMs - Date.now()) / 1e3));
+  }
+  return void 0;
+}
+function sleep2(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);
+  if (parsed === void 0) {
+    await sleep2(DEFAULT_BACKOFF_SECONDS * 1e3);
+    const retried2 = await retryFn();
+    logger.info("proxy.recovery.429_retry_count increment");
+    return retried2;
+  }
+  if (parsed > MAX_RETRY_AFTER_SECONDS) {
+    return response;
+  }
+  await sleep2(parsed * 1e3);
+  const retried = await retryFn();
+  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;
+  }
+  await sleep2(DEFAULT_BACKOFF_SECONDS * 1e3);
+  const retried = await retryFn();
+  logger.info("proxy.recovery.timeout_retry_count increment");
+  return retried;
+}
+function tokenFingerprint(authHeader) {
+  if (authHeader === void 0) return "none";
+  return 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 refreshMutex = new LruMutexMap();
+
 // 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();
+  if (!trimmed) return void 0;
+  const n = Number(trimmed);
+  if (Number.isFinite(n) && n >= 0) return Math.floor(n);
+  const dateMs = Date.parse(trimmed);
+  if (Number.isFinite(dateMs)) {
+    const delta = Math.max(0, Math.ceil((dateMs - Date.now()) / 1e3));
+    return delta;
+  }
+  return void 0;
+}
 var HOP_BY_HOP = /* @__PURE__ */ new Set([
   "connection",
   "keep-alive",
@@ -478,17 +706,11 @@ function stripSkalpelHeaders(headers) {
   delete cleaned["X-Skalpel-Source"];
   delete cleaned["X-Skalpel-Agent-Type"];
   delete cleaned["X-Skalpel-SDK-Version"];
+  delete cleaned["X-Skalpel-Auth-Mode"];
   return cleaned;
 }
-function isSkalpelBackendFailure(response, err) {
-  if (err) return true;
-  if (!response) return true;
-  if (response.status >= 500) return true;
-  if (response.status === 403) return true;
-  return false;
-}
 async function doStreamingFetch(url, body, headers) {
-  return fetch(url, { method: "POST", headers, body });
+  return fetch(url, { method: "POST", headers, body, dispatcher: skalpelDispatcher });
 }
 async function handleStreamingRequest(_req, res, _config, _source, body, skalpelUrl, directUrl, useSkalpel, forwardHeaders, logger) {
   let response = null;
@@ -500,7 +722,7 @@ async function handleStreamingRequest(_req, res, _config, _source, body, skalpel
     } catch (err) {
       fetchError = err;
     }
-    if (isSkalpelBackendFailure(response, fetchError)) {
+    if (await isSkalpelBackendFailure(response, fetchError, logger)) {
       logger.warn(`streaming: Skalpel backend failed (${fetchError ? fetchError.message : `status ${response?.status}`}), falling back to direct Anthropic API`);
       usedFallback = true;
       response = null;
@@ -519,15 +741,40 @@ async function handleStreamingRequest(_req, res, _config, _source, body, skalpel
       fetchError = err;
     }
   }
+  const finalUrl = usedFallback || !useSkalpel ? directUrl : skalpelUrl;
+  const finalHeaders = usedFallback ? stripSkalpelHeaders(forwardHeaders) : forwardHeaders;
+  if (fetchError) {
+    const code = fetchError.code;
+    if (code && TIMEOUT_CODES2.has(code)) {
+      try {
+        response = await handleTimeoutWithRetry(
+          fetchError,
+          () => doStreamingFetch(finalUrl, body, finalHeaders),
+          logger
+        );
+        fetchError = null;
+      } catch (retryErr) {
+        fetchError = retryErr;
+      }
+    }
+  }
+  if (response && response.status === 429) {
+    response = await handle429WithRetryAfter(
+      response,
+      () => doStreamingFetch(finalUrl, body, finalHeaders),
+      logger
+    );
+  }
   if (!response || fetchError) {
     const errMsg = fetchError ? fetchError.message : "no response from upstream";
     logger.error(`streaming fetch failed: ${errMsg}`);
-    res.writeHead(502, {
+    res.writeHead(HTTP_BAD_GATEWAY, {
       "Content-Type": "text/event-stream",
       "Cache-Control": "no-cache"
     });
+    const envelope = buildErrorEnvelope(HTTP_BAD_GATEWAY, errMsg, "skalpel-proxy");
     res.write(`event: error
-data: ${JSON.stringify({ error: errMsg })}
+data: ${JSON.stringify(envelope)}
 
 `);
     res.end();
@@ -537,17 +784,39 @@ data: ${JSON.stringify({ error: errMsg })}
     logger.info("streaming: using direct Anthropic API fallback");
   }
   if (response.status >= 300) {
-    const errorBody = Buffer.from(await response.arrayBuffer());
-    logger.error(`streaming upstream error: status=${response.status} body=${errorBody.toString().slice(0, 500)}`);
-    const passthroughHeaders = {};
-    for (const [key, value] of response.headers.entries()) {
-      if (!STRIP_HEADERS.has(key)) {
-        passthroughHeaders[key] = value;
-      }
+    const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+    const originHeader = response.headers.get("x-skalpel-origin");
+    let origin;
+    if (originHeader === "backend") origin = "skalpel-backend";
+    else if (originHeader === "provider") origin = "provider";
+    else origin = "provider";
+    let rawBody = "";
+    let bodyReadFailed = false;
+    try {
+      rawBody = Buffer.from(await response.arrayBuffer()).toString();
+    } catch (readErr) {
+      bodyReadFailed = true;
+      logger.error(`streaming body-read failed after upstream status: ${readErr.message}`);
+    }
+    if (!bodyReadFailed) {
+      logger.error(`streaming upstream error: status=${response.status} body=${rawBody.slice(0, 500)}`);
     }
-    passthroughHeaders["content-length"] = String(errorBody.length);
-    res.writeHead(response.status, passthroughHeaders);
-    res.end(errorBody);
+    const envelope = bodyReadFailed ? buildErrorEnvelope(
+      response.status,
+      "",
+      "skalpel-proxy",
+      "mid-stream abort",
+      retryAfter
+    ) : buildErrorEnvelope(response.status, rawBody, origin, void 0, retryAfter);
+    res.writeHead(response.status, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache"
+    });
+    res.write(`event: error
+data: ${JSON.stringify(envelope)}
+
+`);
+    res.end();
     return;
   }
   const sseHeaders = {};
@@ -578,8 +847,16 @@ data: ${JSON.stringify({ error: "no response body" })}
     }
   } catch (err) {
     logger.error(`streaming error: ${err.message}`);
+    const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+    const envelope = buildErrorEnvelope(
+      response.status,
+      err.message,
+      "skalpel-proxy",
+      "mid-stream abort",
+      retryAfter
+    );
     res.write(`event: error
-data: ${JSON.stringify({ error: err.message })}
+data: ${JSON.stringify(envelope)}
 
 `);
   }
@@ -587,6 +864,8 @@ data: ${JSON.stringify({ error: err.message })}
 }
 
 // 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"]);
 function collectBody(req) {
   return new Promise((resolve, reject) => {
@@ -597,38 +876,71 @@ function collectBody(req) {
   });
 }
 function shouldRouteToSkalpel(path4, source) {
-  if (isPassthroughMode()) return false;
   if (source !== "claude-code") return true;
   const pathname = path4.split("?")[0];
   return SKALPEL_EXACT_PATHS.has(pathname);
 }
-function isSkalpelBackendFailure2(response, err) {
+async function isSkalpelBackendFailure(response, err, logger) {
   if (err) return true;
   if (!response) return true;
-  if (response.status >= 500) return true;
-  if (response.status === 403) return true;
-  return false;
+  if (response.status < 500) return false;
+  const origin = response.headers?.get("x-skalpel-origin");
+  if (origin === "provider") return false;
+  if (origin === "backend") return true;
+  try {
+    const text = await response.clone().text();
+    if (!text) {
+      logger?.debug(`isSkalpelBackendFailure heuristic: status=${response.status} result=true shape=non-anthropic`);
+      return true;
+    }
+    let shape = "non-anthropic";
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed && typeof parsed === "object" && parsed.type === "error" && parsed.error && typeof parsed.error === "object" && typeof parsed.error.type === "string" && typeof parsed.error.message === "string") {
+        shape = "anthropic";
+        logger?.debug(`isSkalpelBackendFailure heuristic: status=${response.status} result=false shape=${shape}`);
+        return false;
+      }
+    } catch {
+    }
+    logger?.debug(`isSkalpelBackendFailure heuristic: status=${response.status} result=true shape=${shape}`);
+    return true;
+  } catch {
+    logger?.debug(`isSkalpelBackendFailure heuristic: status=${response?.status ?? "null"} result=true shape=non-anthropic`);
+    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)) {
-    if (value !== void 0) {
-      forwardHeaders[key] = Array.isArray(value) ? value.join(", ") : value;
-    }
+    if (value === void 0) continue;
+    if (FORWARD_HEADER_STRIP.has(key.toLowerCase())) continue;
+    forwardHeaders[key] = Array.isArray(value) ? value.join(", ") : value;
   }
-  delete forwardHeaders["host"];
-  delete forwardHeaders["connection"];
   if (useSkalpel) {
     forwardHeaders["X-Skalpel-API-Key"] = config.apiKey;
     forwardHeaders["X-Skalpel-Source"] = source;
     forwardHeaders["X-Skalpel-Agent-Type"] = source;
     forwardHeaders["X-Skalpel-SDK-Version"] = "proxy-1.0.0";
+    forwardHeaders["X-Skalpel-Auth-Mode"] = "passthrough";
     if (source === "claude-code" && !forwardHeaders["x-api-key"]) {
       const authHeader = forwardHeaders["authorization"] ?? "";
       if (authHeader.toLowerCase().startsWith("bearer ")) {
         const token = authHeader.slice(7).trim();
         if (token.startsWith("sk-ant-")) {
           forwardHeaders["x-api-key"] = token;
+          delete forwardHeaders["authorization"];
         }
       }
     }
@@ -641,6 +953,7 @@ function stripSkalpelHeaders2(headers) {
   delete cleaned["X-Skalpel-Source"];
   delete cleaned["X-Skalpel-Agent-Type"];
   delete cleaned["X-Skalpel-SDK-Version"];
+  delete cleaned["X-Skalpel-Auth-Mode"];
   return cleaned;
 }
 var STRIP_RESPONSE_HEADERS = /* @__PURE__ */ new Set([
@@ -668,6 +981,11 @@ async function handleRequest(req, res, config, source, logger) {
   const start = Date.now();
   const method = req.method ?? "GET";
   const path4 = req.url ?? "/";
+  const fp = tokenFingerprint(
+    typeof req.headers.authorization === "string" ? req.headers.authorization : void 0
+  );
+  logger.info(`${source} ${method} ${path4} token=${fp}`);
+  let response = null;
   try {
     const body = await collectBody(req);
     const useSkalpel = shouldRouteToSkalpel(path4, source);
@@ -682,45 +1000,91 @@ async function handleRequest(req, res, config, source, logger) {
     }
     if (isStreaming) {
       const skalpelUrl2 = `${config.remoteBaseUrl}${path4}`;
-      const directUrl2 = `${config.anthropicDirectUrl}${path4}`;
+      const directUrl2 = source === "claude-code" ? `${config.anthropicDirectUrl}${path4}` : source === "cursor" ? `${config.cursorDirectUrl}${path4}` : `${config.openaiDirectUrl}${path4}`;
       await handleStreamingRequest(req, res, config, source, body, skalpelUrl2, directUrl2, useSkalpel, forwardHeaders, logger);
       logger.info(`${method} ${path4} source=${source} streaming latency=${Date.now() - start}ms`);
       return;
     }
     const skalpelUrl = `${config.remoteBaseUrl}${path4}`;
-    const directUrl = `${config.anthropicDirectUrl}${path4}`;
+    const directUrl = source === "claude-code" ? `${config.anthropicDirectUrl}${path4}` : source === "cursor" ? `${config.cursorDirectUrl}${path4}` : `${config.openaiDirectUrl}${path4}`;
     const fetchBody = method !== "GET" && method !== "HEAD" ? body : void 0;
-    let response = null;
     let fetchError = null;
     let usedFallback = false;
     if (useSkalpel) {
       try {
-        response = await fetch(skalpelUrl, { method, headers: forwardHeaders, body: fetchBody });
+        response = await fetch(skalpelUrl, { method, headers: forwardHeaders, body: fetchBody, dispatcher: skalpelDispatcher });
       } catch (err) {
         fetchError = err;
       }
-      if (isSkalpelBackendFailure2(response, fetchError)) {
+      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`);
         usedFallback = true;
         response = null;
         fetchError = null;
         const directHeaders = stripSkalpelHeaders2(forwardHeaders);
         try {
-          response = await fetch(directUrl, { method, headers: directHeaders, body: fetchBody });
+          response = await fetch(directUrl, { method, headers: directHeaders, body: fetchBody, dispatcher: skalpelDispatcher });
         } catch (err) {
           fetchError = err;
         }
       }
     } else {
       try {
-        response = await fetch(directUrl, { method, headers: forwardHeaders, body: fetchBody });
+        response = await fetch(directUrl, { method, headers: forwardHeaders, body: fetchBody, dispatcher: skalpelDispatcher });
       } catch (err) {
         fetchError = err;
       }
     }
+    const fetchUrl = usedFallback || !useSkalpel ? directUrl : skalpelUrl;
+    const fetchHeaders = usedFallback ? stripSkalpelHeaders2(forwardHeaders) : forwardHeaders;
+    if (fetchError) {
+      const code = fetchError.code;
+      if (code && TIMEOUT_CODES3.has(code)) {
+        try {
+          response = await handleTimeoutWithRetry(
+            fetchError,
+            () => fetch(fetchUrl, {
+              method,
+              headers: fetchHeaders,
+              body: fetchBody,
+              dispatcher: skalpelDispatcher
+            }),
+            logger
+          );
+          fetchError = null;
+        } catch (retryErr) {
+          fetchError = retryErr;
+        }
+      }
+    }
     if (!response || fetchError) {
+      response = null;
       throw fetchError ?? new Error("no response from upstream");
     }
+    if (response.status === 429) {
+      response = await handle429WithRetryAfter(
+        response,
+        () => fetch(fetchUrl, {
+          method,
+          headers: fetchHeaders,
+          body: fetchBody,
+          dispatcher: skalpelDispatcher
+        }),
+        logger
+      );
+    }
+    if (response.status === 401 && (source === "claude-code" || source === "codex")) {
+      const fp2 = tokenFingerprint(
+        typeof req.headers.authorization === "string" ? req.headers.authorization : void 0
+      );
+      logger.debug(`handler: upstream 401 origin=provider token=${fp2} passthrough`);
+      const body401 = Buffer.from(await response.arrayBuffer());
+      const envelope = buildErrorEnvelope(401, body401.toString(), "provider");
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(envelope));
+      logger.info(`${method} ${path4} source=${source} status=401 (passthrough) latency=${Date.now() - start}ms`);
+      return;
+    }
     const responseHeaders = extractResponseHeaders(response);
     const responseBody = Buffer.from(await response.arrayBuffer());
     responseHeaders["content-length"] = String(responseBody.length);
@@ -730,21 +1094,38 @@ async function handleRequest(req, res, config, source, logger) {
   } catch (err) {
     logger.error(`${method} ${path4} source=${source} error=${err.message}`);
     if (!res.headersSent) {
-      res.writeHead(502, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ error: "proxy_error", message: err.message }));
+      if (response !== null) {
+        const upstreamStatus = response.status;
+        const envelope = buildErrorEnvelope(
+          upstreamStatus,
+          "",
+          "skalpel-proxy",
+          "body read failed after upstream status"
+        );
+        res.writeHead(upstreamStatus, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(envelope));
+      } else {
+        const envelope = buildErrorEnvelope(
+          HTTP_BAD_GATEWAY2,
+          err.message,
+          "skalpel-proxy"
+        );
+        res.writeHead(HTTP_BAD_GATEWAY2, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(envelope));
+      }
     }
   }
 }
 
 // src/proxy/health.ts
-function handleHealthRequest(res, config, startTime, passthrough = false) {
+function handleHealthRequest(res, config, startTime) {
   const body = JSON.stringify({
     status: "ok",
-    mode: passthrough ? "passthrough" : "normal",
     uptime: Date.now() - startTime,
     ports: {
       anthropic: config.anthropicPort,
-      openai: config.openaiPort
+      openai: config.openaiPort,
+      cursor: config.cursorPort
     },
     version: "proxy-1.0.0"
   });
@@ -755,13 +1136,29 @@ function handleHealthRequest(res, config, startTime, passthrough = false) {
 // src/proxy/pid.ts
 import fs from "fs";
 import path from "path";
+import { execSync } from "child_process";
 function writePid(pidFile) {
   fs.mkdirSync(path.dirname(pidFile), { recursive: true });
-  fs.writeFileSync(pidFile, String(process.pid));
+  const record = {
+    pid: process.pid,
+    startTime: getStartTime(process.pid)
+  };
+  fs.writeFileSync(pidFile, JSON.stringify(record));
 }
 function readPid(pidFile) {
   try {
     const raw = fs.readFileSync(pidFile, "utf-8").trim();
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && typeof parsed.pid === "number" && !isNaN(parsed.pid)) {
+        const record = parsed;
+        if (record.startTime == null) {
+          return isRunning(record.pid) ? record.pid : null;
+        }
+        return isRunningWithIdentity(record.pid, record.startTime) ? record.pid : null;
+      }
+    } catch {
+    }
     const pid = parseInt(raw, 10);
     if (isNaN(pid)) return null;
     return isRunning(pid) ? pid : null;
@@ -777,6 +1174,37 @@ function isRunning(pid) {
     return false;
   }
 }
+function getStartTime(pid) {
+  try {
+    if (process.platform === "linux") {
+      const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf-8");
+      const rparen = stat.lastIndexOf(")");
+      if (rparen < 0) return null;
+      const fields = stat.slice(rparen + 2).split(" ");
+      return fields[19] ?? null;
+    }
+    if (process.platform === "darwin") {
+      const out = execSync(`ps -p ${pid} -o lstart=`, { timeout: 2e3, stdio: ["ignore", "pipe", "ignore"] });
+      const text = out.toString().trim();
+      return text || null;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function isRunningWithIdentity(pid, expectedStartTime) {
+  try {
+    if (process.platform !== "linux" && process.platform !== "darwin") {
+      return isRunning(pid);
+    }
+    const current = getStartTime(pid);
+    if (current == null) return false;
+    return current === expectedStartTime;
+  } catch {
+    return false;
+  }
+}
 function removePid(pidFile) {
   try {
     fs.unlinkSync(pidFile);
@@ -790,12 +1218,14 @@ import path2 from "path";
 var MAX_SIZE = 5 * 1024 * 1024;
 var MAX_ROTATIONS = 3;
 var LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
-var Logger = class {
+var Logger = class _Logger {
   logFile;
   level;
-  constructor(logFile, level = "info") {
+  prefix;
+  constructor(logFile, level = "info", prefix = "") {
     this.logFile = logFile;
     this.level = level;
+    this.prefix = prefix;
     fs2.mkdirSync(path2.dirname(logFile), { recursive: true });
   }
   debug(msg) {
@@ -810,9 +1240,16 @@ var Logger = class {
   error(msg) {
     this.log("error", msg);
   }
+  /** Returns a new Logger that writes to the same file but prefixes every
+   *  emitted line with `[conn=<connId>] `. The parent logger continues to
+   *  work unchanged. IPv6 colons should already be sanitized by the caller. */
+  child(connId) {
+    const child = new _Logger(this.logFile, this.level, `[conn=${connId}] `);
+    return child;
+  }
   log(level, msg) {
     if (LEVELS[level] < LEVELS[this.level]) return;
-    const line = `${(/* @__PURE__ */ new Date()).toISOString()} [${level.toUpperCase()}] ${msg}
+    const line = `${(/* @__PURE__ */ new Date()).toISOString()} [${level.toUpperCase()}] ${this.prefix}${msg}
 `;
     if (level === "debug" || level === "error") {
       process.stderr.write(line);
@@ -843,61 +1280,41 @@ var Logger = class {
 
 // src/proxy/server.ts
 var proxyStartTime = 0;
-var passthroughMode = false;
-function isPassthroughMode() {
-  return passthroughMode;
-}
-function collectAdminBody(req) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    req.on("data", (chunk) => chunks.push(chunk));
-    req.on("end", () => resolve(Buffer.concat(chunks).toString()));
-    req.on("error", reject);
-  });
-}
-function handleAdminMode(req, res, logger) {
-  collectAdminBody(req).then((body) => {
-    try {
-      const { mode } = JSON.parse(body);
-      passthroughMode = mode === "passthrough";
-      logger.info(`Proxy mode changed to: ${passthroughMode ? "passthrough" : "normal"}`);
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ mode: passthroughMode ? "passthrough" : "normal" }));
-    } catch {
-      res.writeHead(400, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ error: "invalid JSON body" }));
-    }
-  }).catch(() => {
-    res.writeHead(500, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "failed to read body" }));
-  });
+var connCounter = 0;
+function computeConnId(req) {
+  const addr = req.socket.remoteAddress ?? "unknown";
+  const port = req.socket.remotePort ?? 0;
+  const counter = (++connCounter).toString(36);
+  const raw = addr + "|" + port + "|" + Date.now().toString(36) + "|" + counter + "|" + Math.floor(Math.random() * 4096).toString(16);
+  return raw.replace(/:/g, "_");
 }
 function startProxy(config) {
   const logger = new Logger(config.logFile, config.logLevel);
   const startTime = Date.now();
   proxyStartTime = Date.now();
-  passthroughMode = false;
   const anthropicServer = http.createServer((req, res) => {
     if (req.url === "/health" && req.method === "GET") {
-      handleHealthRequest(res, config, startTime, isPassthroughMode());
-      return;
-    }
-    if (req.url === "/admin/mode" && req.method === "POST") {
-      handleAdminMode(req, res, logger);
+      handleHealthRequest(res, config, startTime);
       return;
     }
-    handleRequest(req, res, config, "claude-code", logger);
+    const connId = computeConnId(req);
+    handleRequest(req, res, config, "claude-code", logger.child(connId));
   });
   const openaiServer = http.createServer((req, res) => {
     if (req.url === "/health" && req.method === "GET") {
-      handleHealthRequest(res, config, startTime, isPassthroughMode());
+      handleHealthRequest(res, config, startTime);
       return;
     }
-    if (req.url === "/admin/mode" && req.method === "POST") {
-      handleAdminMode(req, res, logger);
+    const connId = computeConnId(req);
+    handleRequest(req, res, config, "codex", logger.child(connId));
+  });
+  const cursorServer = http.createServer((req, res) => {
+    if (req.url === "/health" && req.method === "GET") {
+      handleHealthRequest(res, config, startTime);
       return;
     }
-    handleRequest(req, res, config, "codex", logger);
+    const connId = computeConnId(req);
+    handleRequest(req, res, config, "cursor", logger.child(connId));
   });
   anthropicServer.on("error", (err) => {
     if (err.code === "EADDRINUSE") {
@@ -917,18 +1334,31 @@ function startProxy(config) {
     removePid(config.pidFile);
     process.exit(1);
   });
+  cursorServer.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+      logger.error(`Port ${config.cursorPort} is already in use. Another Skalpel proxy or process may be running.`);
+    } else {
+      logger.error(`Cursor proxy failed to bind port ${config.cursorPort}: ${err.message}`);
+    }
+    removePid(config.pidFile);
+    process.exit(1);
+  });
   anthropicServer.listen(config.anthropicPort, () => {
     logger.info(`Anthropic proxy listening on port ${config.anthropicPort}`);
   });
   openaiServer.listen(config.openaiPort, () => {
     logger.info(`OpenAI proxy listening on port ${config.openaiPort}`);
   });
+  cursorServer.listen(config.cursorPort, () => {
+    logger.info(`Cursor proxy listening on port ${config.cursorPort}`);
+  });
   writePid(config.pidFile);
-  logger.info(`Proxy started (pid=${process.pid}) ports=${config.anthropicPort},${config.openaiPort}`);
+  logger.info(`Proxy started (pid=${process.pid}) ports=${config.anthropicPort},${config.openaiPort},${config.cursorPort}`);
   const cleanup = () => {
     logger.info("Shutting down proxy...");
     anthropicServer.close();
     openaiServer.close();
+    cursorServer.close();
     removePid(config.pidFile);
     process.exit(0);
   };
@@ -944,7 +1374,7 @@ function startProxy(config) {
     removePid(config.pidFile);
     process.exit(1);
   });
-  return { anthropicServer, openaiServer };
+  return { anthropicServer, openaiServer, cursorServer };
 }
 function stopProxy(config) {
   const pid = readPid(config.pidFile);
@@ -963,7 +1393,8 @@ function getProxyStatus(config) {
     pid,
     uptime: proxyStartTime > 0 ? Date.now() - proxyStartTime : 0,
     anthropicPort: config.anthropicPort,
-    openaiPort: config.openaiPort
+    openaiPort: config.openaiPort,
+    cursorPort: config.cursorPort
   };
 }
 
@@ -981,13 +1412,20 @@ var DEFAULTS = {
   apiKey: "",
   remoteBaseUrl: "https://api.skalpel.ai",
   anthropicDirectUrl: "https://api.anthropic.com",
+  openaiDirectUrl: "https://api.openai.com",
   anthropicPort: 18100,
   openaiPort: 18101,
+  cursorPort: 18102,
+  cursorDirectUrl: "https://api.openai.com",
   logLevel: "info",
   logFile: "~/.skalpel/logs/proxy.log",
   pidFile: "~/.skalpel/proxy.pid",
-  configFile: "~/.skalpel/config.json"
+  configFile: "~/.skalpel/config.json",
+  mode: "proxy"
 };
+function coerceMode(value) {
+  return value === "direct" ? "direct" : "proxy";
+}
 function loadConfig(configPath) {
   const filePath = expandHome(configPath ?? DEFAULTS.configFile);
   let fileConfig = {};
@@ -1000,18 +1438,27 @@ function loadConfig(configPath) {
     apiKey: fileConfig.apiKey ?? DEFAULTS.apiKey,
     remoteBaseUrl: fileConfig.remoteBaseUrl ?? DEFAULTS.remoteBaseUrl,
     anthropicDirectUrl: fileConfig.anthropicDirectUrl ?? DEFAULTS.anthropicDirectUrl,
+    openaiDirectUrl: fileConfig.openaiDirectUrl ?? DEFAULTS.openaiDirectUrl,
     anthropicPort: fileConfig.anthropicPort ?? DEFAULTS.anthropicPort,
     openaiPort: fileConfig.openaiPort ?? DEFAULTS.openaiPort,
+    cursorPort: fileConfig.cursorPort ?? DEFAULTS.cursorPort,
+    cursorDirectUrl: fileConfig.cursorDirectUrl ?? DEFAULTS.cursorDirectUrl,
     logLevel: fileConfig.logLevel ?? DEFAULTS.logLevel,
     logFile: expandHome(fileConfig.logFile ?? DEFAULTS.logFile),
     pidFile: expandHome(fileConfig.pidFile ?? DEFAULTS.pidFile),
-    configFile: filePath
+    configFile: filePath,
+    mode: coerceMode(fileConfig.mode)
   };
 }
 function saveConfig(config) {
   const dir = path3.dirname(config.configFile);
   fs3.mkdirSync(dir, { recursive: true });
-  fs3.writeFileSync(config.configFile, JSON.stringify(config, null, 2) + "\n");
+  const { mode, ...rest } = config;
+  const serializable = { ...rest };
+  if (mode === "direct") {
+    serializable.mode = mode;
+  }
+  fs3.writeFileSync(config.configFile, JSON.stringify(serializable, null, 2) + "\n");
 }
 export {
   SkalpelAuthError,