@amir83nasr/10router 0.1.0

package/open-sse/utils/streamHandler.js

@@ -0,0 +1,329 @@
+// Stream handler with disconnect detection - shared for all providers
+import { STREAM_STALL_TIMEOUT_MS } from "../config/runtimeConfig.js";
+import { dbg, isDebugEnabled } from "./debugLog.js";
+
+// Get HH:MM:SS timestamp
+function getTimeString() {
+  return new Date().toLocaleTimeString("en-US", {
+    hour12: false,
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  });
+}
+
+/**
+ * Create stream controller with abort and disconnect detection
+ * @param {object} options
+ * @param {function} options.onDisconnect - Callback when client disconnects
+ * @param {object} options.log - Logger instance
+ * @param {string} options.provider - Provider name
+ * @param {string} options.model - Model name
+ */
+export function createStreamController({
+  onDisconnect,
+  onError,
+  log,
+  provider,
+  model,
+  reqTag = "",
+} = {}) {
+  const abortController = new AbortController();
+  const startTime = Date.now();
+  let disconnected = false;
+  let abortTimeout = null;
+
+  // Only abnormal terminations are logged; normal completion is covered by "DONE".
+  // isError uses errorLine (always shown, ignores LOG_LEVEL) so failures survive quiet levels.
+  const logStream = (symbol, status, isError = false) => {
+    const duration = Date.now() - startTime;
+    const emit = isError ? log?.errorLine : log?.line;
+    if (emit) emit(reqTag, symbol, `${status} · ${provider}/${model} · ${duration}ms`);
+    else
+      console.log(
+        `[${getTimeString()}] ${symbol} ${provider}/${model} · ${status} · ${duration}ms`,
+      );
+  };
+
+  return {
+    signal: abortController.signal,
+    startTime,
+
+    isConnected: () => !disconnected,
+
+    // Call when client disconnects
+    handleDisconnect: (reason = "client_closed") => {
+      if (disconnected) return;
+      disconnected = true;
+
+      // Debug-only: Responses API has no [DONE] sentinel, so codex/droid close the
+      // socket on every completed request. "DONE" is the authoritative outcome line.
+      dbg("CTRL", `${provider}/${model} | disconnect=${reason} | dur=${Date.now() - startTime}ms`);
+
+      // Delay abort to allow cleanup
+      abortTimeout = setTimeout(() => {
+        abortController.abort();
+      }, 500);
+
+      onDisconnect?.({ reason, duration: Date.now() - startTime });
+    },
+
+    // Call when stream completes normally (no line here — "DONE" is authoritative)
+    handleComplete: () => {
+      if (disconnected) return;
+      disconnected = true;
+
+      if (abortTimeout) {
+        clearTimeout(abortTimeout);
+        abortTimeout = null;
+      }
+    },
+
+    // Call on error
+    handleError: (error) => {
+      if (disconnected) return;
+      disconnected = true;
+
+      if (abortTimeout) {
+        clearTimeout(abortTimeout);
+        abortTimeout = null;
+      }
+
+      if (error.name === "AbortError") {
+        logStream("ABORT", "ABORTED");
+        return;
+      }
+
+      logStream(
+        "ERROR",
+        `ERROR: ${error.message}${error.stack ? `\n    ${error.stack}` : ""}`,
+        true,
+      );
+      onError?.(error);
+    },
+
+    abort: () => abortController.abort(),
+  };
+}
+
+/**
+ * Create transform stream with disconnect detection
+ * Wraps existing transform stream and adds abort capability.
+ *
+ * Stall detection lives in pipeWithDisconnect (tied to upstream byte
+ * activity), not here — output of the transform stream may be silent
+ * for long periods while raw bytes still flow (e.g. Kiro EventStream
+ * binary frames buffering, Claude reasoning streams).
+ *
+ * @param {function} [onAbortTerminal] - Receives a human-readable abort
+ * message and returns terminal SSE bytes to emit downstream.
+ */
+export function createDisconnectAwareStream(
+  transformStream,
+  streamController,
+  onAbortTerminal = null,
+) {
+  const reader = transformStream.readable.getReader();
+  const writer = transformStream.writable.getWriter();
+  let terminalEmitted = false;
+
+  // Emit a synthesized terminal payload (e.g. Responses response.failed + [DONE]) once
+  const emitTerminal = (controller) => {
+    if (terminalEmitted || !onAbortTerminal) return;
+    terminalEmitted = true;
+    try {
+      const bytes = onAbortTerminal();
+      if (bytes) controller.enqueue(bytes);
+    } catch {
+      /* best-effort terminal */
+    }
+  };
+
+  return new ReadableStream({
+    async pull(controller) {
+      if (!streamController.isConnected()) {
+        emitTerminal(controller);
+        controller.close();
+        return;
+      }
+
+      try {
+        const { done, value } = await reader.read();
+
+        if (done) {
+          streamController.handleComplete();
+          controller.close();
+          return;
+        }
+        controller.enqueue(value);
+      } catch (error) {
+        const wasConnected = streamController.isConnected();
+        // Controller already closed = downstream ended; not an upstream error, skip noisy log.
+        const msg0 = error?.message || "";
+        const isControllerClosed =
+          msg0.includes("already closed") || msg0.includes("Invalid state");
+        if (!isControllerClosed) streamController.handleError(error);
+        reader.cancel().catch(() => {});
+        writer.abort().catch(() => {});
+
+        // Treat network resets / socket hang up / abort as graceful close
+        const msg = error?.message || "";
+        const code = error?.code || error?.cause?.code || "";
+        const isNetworkClose =
+          error.name === "AbortError" ||
+          msg.includes("aborted") ||
+          msg.includes("socket hang up") ||
+          msg.includes("ECONNRESET") ||
+          msg.includes("ETIMEDOUT") ||
+          msg.includes("EPIPE") ||
+          code === "ECONNRESET" ||
+          code === "ETIMEDOUT" ||
+          code === "EPIPE" ||
+          code === "UND_ERR_SOCKET";
+
+        // Graceful close on network/abort, or when a structured terminal is available
+        // (Responses passthrough prefers response.failed + [DONE] over a raw transport error)
+        try {
+          if (!wasConnected || isNetworkClose || onAbortTerminal) {
+            emitTerminal(controller);
+            controller.close();
+          } else {
+            controller.error(error);
+          }
+        } catch (e) {
+          /* already closed or cancelled */
+        }
+      }
+    },
+
+    cancel(reason) {
+      streamController.handleDisconnect(reason || "cancelled");
+      reader.cancel();
+      writer.abort();
+    },
+  });
+}
+
+/**
+ * Pipe provider response through transform with disconnect detection.
+ *
+ * Stall watchdog tracks raw upstream byte activity, not transform output.
+ * Reasoning models (Claude thinking via Kiro, etc.) can produce zero SSE
+ * output for long stretches while partial EventStream frames keep arriving.
+ * Measuring stall on the transform output caused false stalls and the
+ * "failed to pipe response" error in Next.
+ *
+ * Any upstream chunk resets the timer. If no bytes arrive for
+ * STREAM_STALL_TIMEOUT_MS, abort the underlying fetch via the controller.
+ *
+ * @param {Response} providerResponse - Response from provider
+ * @param {TransformStream} transformStream - Transform stream for SSE
+ * @param {object} streamController - Stream controller from createStreamController
+ */
+export function pipeWithDisconnect(
+  providerResponse,
+  transformStream,
+  streamController,
+  onAbortTerminal = null,
+  stallTimeoutMs = STREAM_STALL_TIMEOUT_MS,
+) {
+  let stallTimer = null;
+  let chunkCount = 0;
+  let totalBytes = 0;
+  let lastChunkAt = Date.now();
+  let abortMessage = "upstream connection lost";
+  const t0 = Date.now();
+  const tag = "STREAM";
+  const clearStall = () => {
+    if (stallTimer) {
+      clearTimeout(stallTimer);
+      stallTimer = null;
+    }
+  };
+  const armStall = () => {
+    clearStall();
+    stallTimer = setTimeout(() => {
+      stallTimer = null;
+      abortMessage = "stream stall timeout";
+      dbg(
+        tag,
+        `STALL TIMEOUT ${stallTimeoutMs}ms | chunks=${chunkCount} | bytes=${totalBytes} | sinceLast=${Date.now() - lastChunkAt}ms`,
+      );
+      streamController.handleError?.(new Error("stream stall timeout"));
+      streamController.abort?.();
+    }, stallTimeoutMs);
+  };
+
+  // Wrap controller so every termination path clears the stall timer.
+  // Without this, abort/cancel/downstream-error paths leave the timer armed
+  // and a stale abort could fire after the request has already ended.
+  const wrappedController = {
+    signal: streamController.signal,
+    startTime: streamController.startTime,
+    isConnected: () => streamController.isConnected(),
+    handleComplete: () => {
+      dbg(tag, `complete | chunks=${chunkCount} | bytes=${totalBytes} | dur=${Date.now() - t0}ms`);
+      clearStall();
+      streamController.handleComplete();
+    },
+    handleError: (e) => {
+      dbg(
+        tag,
+        `error: ${e?.message} | chunks=${chunkCount} | bytes=${totalBytes} | dur=${Date.now() - t0}ms`,
+      );
+      clearStall();
+      streamController.handleError(e);
+    },
+    handleDisconnect: (r) => {
+      dbg(
+        tag,
+        `disconnect: ${r} | chunks=${chunkCount} | bytes=${totalBytes} | dur=${Date.now() - t0}ms`,
+      );
+      clearStall();
+      streamController.handleDisconnect(r);
+    },
+    abort: () => {
+      clearStall();
+      streamController.abort();
+    },
+  };
+
+  armStall();
+  dbg(tag, `pipe start | stallTimeout=${stallTimeoutMs}ms`);
+
+  const upstreamTap = new TransformStream({
+    transform(chunk, controller) {
+      chunkCount++;
+      const sz = chunk?.byteLength || chunk?.length || 0;
+      totalBytes += sz;
+      const now = Date.now();
+      const gap = now - lastChunkAt;
+      lastChunkAt = now;
+      if (isDebugEnabled && (chunkCount <= 5 || chunkCount % 20 === 0 || gap > 5000)) {
+        dbg(tag, `chunk #${chunkCount} | size=${sz}B | gap=${gap}ms | total=${totalBytes}B`);
+      }
+      armStall();
+      controller.enqueue(chunk);
+    },
+    flush() {
+      dbg(
+        tag,
+        `upstream EOF | chunks=${chunkCount} | bytes=${totalBytes} | dur=${Date.now() - t0}ms`,
+      );
+      clearStall();
+    },
+  });
+
+  const transformedBody = providerResponse.body
+    .pipeThrough(upstreamTap)
+    .pipeThrough(transformStream);
+
+  return createDisconnectAwareStream(
+    {
+      readable: transformedBody,
+      writable: { getWriter: () => ({ abort: () => Promise.resolve() }) },
+    },
+    wrappedController,
+    onAbortTerminal ? () => onAbortTerminal(abortMessage) : null,
+  );
+}

package/open-sse/utils/streamHelpers.js

@@ -0,0 +1,155 @@
+import { FORMATS } from "../translator/formats.js";
+import { buildErrorBody } from "./error.js";
+import { SSE_DONE } from "./sseConstants.js";
+
+const sharedEncoder = new TextEncoder();
+
+// Parse SSE data line
+export function parseSSELine(line, format = null) {
+  if (!line) return null;
+
+  // NDJSON format (Ollama): raw JSON lines without "data:" prefix.
+  // Also accept them without an explicit format — a line starting with "{"
+  // can never be a valid SSE "data:" line, so parsing it as JSON is safe.
+  const trimmed = line.trim();
+  if (trimmed.startsWith("{") && (format === FORMATS.OLLAMA || format == null)) {
+    try {
+      return JSON.parse(trimmed);
+    } catch (error) {
+      return null;
+    }
+  }
+  if (format === FORMATS.OLLAMA) return null;
+
+  // Standard SSE format: "data: {...}"
+  if (line.charCodeAt(0) !== 100) return null; // 'd' = 100
+
+  const data = line.slice(5).trim();
+  if (data === "[DONE]") return { done: true };
+
+  try {
+    return JSON.parse(data);
+  } catch (error) {
+    if (data.length > 0 && data.length < 1000) {
+      console.log(
+        `[WARN] Failed to parse SSE line (${data.length} chars): ${data.substring(0, 100)}...`,
+      );
+    }
+    return null;
+  }
+}
+
+// Check if chunk has valuable content (not empty)
+export function hasValuableContent(chunk, format) {
+  // OpenAI format
+  if (format === FORMATS.OPENAI && chunk.choices?.[0]?.delta) {
+    const delta = chunk.choices[0].delta;
+    return (
+      (delta.content && delta.content !== "") ||
+      (delta.reasoning_content && delta.reasoning_content !== "") ||
+      (delta.tool_calls && delta.tool_calls.length > 0) ||
+      chunk.choices[0].finish_reason ||
+      delta.role
+    );
+  }
+
+  // Claude format
+  if (format === FORMATS.CLAUDE) {
+    const isContentBlockDelta = chunk.type === "content_block_delta";
+    const hasText = chunk.delta?.text && chunk.delta.text !== "";
+    const hasThinking = chunk.delta?.thinking && chunk.delta.thinking !== "";
+    const hasInputJson = chunk.delta?.partial_json && chunk.delta.partial_json !== "";
+
+    if (isContentBlockDelta && !hasText && !hasThinking && !hasInputJson) {
+      return false;
+    }
+    return true;
+  }
+
+  return true; // Other formats: keep all chunks
+}
+
+// Fix invalid id (generic or too short)
+export function fixInvalidId(parsed) {
+  if (parsed.id && (parsed.id === "chat" || parsed.id === "completion" || parsed.id.length < 8)) {
+    const fallbackId =
+      parsed.extend_fields?.requestId || parsed.extend_fields?.traceId || Date.now().toString(36);
+    parsed.id = `chatcmpl-${fallbackId}`;
+    return true;
+  }
+  return false;
+}
+
+function cleanUsagePayload(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return payload;
+  }
+
+  let cleaned = payload;
+
+  if ("usage" in cleaned) {
+    if (cleaned.usage === null) {
+      const { usage, ...payloadWithoutUsage } = cleaned;
+      cleaned = payloadWithoutUsage;
+    } else if (typeof cleaned.usage === "object" && cleaned.usage.perf_metrics === null) {
+      const { perf_metrics, ...usageWithoutPerf } = cleaned.usage;
+      cleaned = { ...cleaned, usage: usageWithoutPerf };
+    }
+  }
+
+  if (
+    cleaned.response &&
+    typeof cleaned.response === "object" &&
+    !Array.isArray(cleaned.response)
+  ) {
+    const cleanedResponse = cleanUsagePayload(cleaned.response);
+    if (cleanedResponse !== cleaned.response) {
+      cleaned = { ...cleaned, response: cleanedResponse };
+    }
+  }
+
+  return cleaned;
+}
+
+// Format output as SSE
+export function formatSSE(data, sourceFormat) {
+  if (data === null || data === undefined) return "data: null\n\n";
+  if (data && data.done) return "data: [DONE]\n\n";
+
+  // OpenAI Responses API format
+  if (data && data.event && data.data) {
+    const cleanedEventData = cleanUsagePayload(data.data);
+    return `event: ${data.event}\ndata: ${JSON.stringify(cleanedEventData)}\n\n`;
+  }
+
+  data = cleanUsagePayload(data);
+
+  // Claude format
+  if (sourceFormat === FORMATS.CLAUDE && data && data.type) {
+    return `event: ${data.type}\ndata: ${JSON.stringify(data)}\n\n`;
+  }
+
+  return `data: ${JSON.stringify(data)}\n\n`;
+}
+
+// Terminal frames for a stream that aborted after HTTP 200 was already sent, so
+// the status code can no longer change. OpenAI-compatible clients (openai-python
+// raises APIError on any `data:` payload carrying an `error` key, checked before
+// [DONE]) need the error frame first, then [DONE]; Anthropic clients need
+// `event: error`. Never fabricate a successful finish_reason instead.
+//
+// Returns encoded bytes: onAbortTerminal callbacks are enqueued verbatim, same
+// as buildAbortedResponsesTerminalBytes.
+//
+// NOTE: non-SSE client formats (Ollama NDJSON) get an SSE frame here — dead in
+// practice because detectFormatByEndpoint never resolves to OLLAMA.
+export function buildStreamErrorBytes(statusCode, message, clientFormat) {
+  const { error } = buildErrorBody(statusCode, message);
+
+  const sse =
+    clientFormat === FORMATS.CLAUDE
+      ? formatSSE({ type: "error", error }, FORMATS.CLAUDE)
+      : formatSSE({ error }, clientFormat) + SSE_DONE;
+
+  return sharedEncoder.encode(sse);
+}

package/open-sse/utils/toolDeduper.js

@@ -0,0 +1,49 @@
+/**
+ * Strip built-in/duplicate tools when equivalent MCP tools are present.
+ * Goal: reduce tool definitions token bloat for Claude clients.
+ */
+
+const DEDUP_RULES = [
+  {
+    // Exa MCP present → drop built-in web tools (Exa is preferred).
+    triggers: ["mcp__exa__web_search_exa", "mcp__exa__web_fetch_exa"],
+    strip: ["WebSearch", "WebFetch", "mcp__workspace__web_fetch"],
+  },
+  {
+    // Tavily MCP present → drop built-in web tools.
+    triggers: ["mcp__tavily__tavily_search", "mcp__tavily__tavily_extract"],
+    strip: ["WebSearch", "WebFetch", "mcp__workspace__web_fetch"],
+  },
+  {
+    // Browser MCP present → drop Cowork's duplicate Claude_in_Chrome connector.
+    triggers: [/^mcp__browsermcp__/],
+    strip: [/^mcp__Claude_in_Chrome__/],
+  },
+];
+
+function getToolName(t) {
+  return t?.name || t?.function?.name || "";
+}
+
+function matches(name, pattern) {
+  if (typeof pattern === "string") return name === pattern;
+  return pattern instanceof RegExp ? pattern.test(name) : false;
+}
+
+function dedupeTools(tools) {
+  if (!Array.isArray(tools) || tools.length === 0) return { tools, stripped: [] };
+  const names = tools.map(getToolName);
+  const toStrip = new Set();
+  for (const rule of DEDUP_RULES) {
+    const hasTrigger = names.some((n) => rule.triggers.some((p) => matches(n, p)));
+    if (!hasTrigger) continue;
+    for (const n of names) {
+      if (rule.strip.some((p) => matches(n, p))) toStrip.add(n);
+    }
+  }
+  if (toStrip.size === 0) return { tools, stripped: [] };
+  const out = tools.filter((t) => !toStrip.has(getToolName(t)));
+  return { tools: out, stripped: Array.from(toStrip) };
+}
+
+export { dedupeTools };