@gethelio/proxy 0.1.1 → 0.3.0

package/dist/index.js

@@ -37,7 +37,8 @@ var upstreamSchema = z.object({
   args: z.array(z.string()).optional(),
   connect_timeout: durationSchema.default("10s"),
   request_timeout: durationSchema.default("30s"),
-  forward_headers: z.array(z.string().min(1)).default([])
+  forward_headers: z.array(z.string().min(1)).default([]),
+  headers: z.record(z.string(), z.string()).default({})
 }).refine((data) => data.transport !== "stdio" || data.command !== void 0, {
   message: '"command" is required when transport is "stdio"',
   path: ["command"]
@@ -51,6 +52,22 @@ var upstreamSchema = z.object({
       });
     }
   }
+  const reserved = /* @__PURE__ */ new Set([
+    "mcp-session-id",
+    "mcp-protocol-version",
+    "content-type",
+    "content-length",
+    "host"
+  ]);
+  for (const name of Object.keys(data.headers)) {
+    if (reserved.has(name.toLowerCase())) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["headers", name],
+        message: `upstream.headers must not set reserved header "${name}"`
+      });
+    }
+  }
 });
 var listenSchema = z.object({
   port: z.number().int().min(1).max(65535).default(3e3),
@@ -1092,6 +1109,93 @@ async function parseUpstreamResponse(res) {
   return { status: res.status, headers, body };
 }
 
+// src/upstream/sse-parse.ts
+function parseSseChunk(chunk, state, onEvent) {
+  let { event, data, remainder } = state;
+  const text = remainder + chunk;
+  const lines = text.split("\n");
+  remainder = lines.pop() ?? "";
+  for (const rawLine of lines) {
+    const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+    if (line === "") {
+      if (event || data) {
+        onEvent(event, data);
+        event = "";
+        data = "";
+      }
+    } else if (line.startsWith("event:")) {
+      const value = line.slice(6).replace(/^ /, "");
+      event = value;
+    } else if (line.startsWith("data:")) {
+      const value = line.slice(5).replace(/^ /, "");
+      data = data ? data + "\n" + value : value;
+    }
+  }
+  return { event, data, remainder };
+}
+async function readSseJsonRpcResponse(res, requestId) {
+  if (!res.body) {
+    throw new Error("upstream SSE response had no body");
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let state = { event: "", data: "", remainder: "" };
+  let found;
+  const onEvent = (event, data) => {
+    if (event && event !== "message") return;
+    let parsed;
+    try {
+      parsed = JSON.parse(data);
+    } catch {
+      return;
+    }
+    if (parsed === null || typeof parsed !== "object") return;
+    const id = parsed["id"];
+    if (id === requestId) {
+      found = parsed;
+    }
+  };
+  const processChunk = (chunk) => {
+    state = parseSseChunk(chunk, state, onEvent);
+  };
+  for (; ; ) {
+    const result = await reader.read();
+    if (result.value !== void 0) {
+      const chunk = result.value;
+      processChunk(decoder.decode(chunk, { stream: true }));
+      if (found) {
+        await reader.cancel().catch(() => void 0);
+        return found;
+      }
+    }
+    if (result.done) {
+      const tail = decoder.decode();
+      if (tail) {
+        processChunk(tail);
+        if (found) return found;
+      }
+      break;
+    }
+  }
+  throw new Error(
+    `upstream SSE stream closed with no JSON-RPC response for id ${String(requestId)}`
+  );
+}
+
+// src/upstream/merge-headers.ts
+function mergeUpstreamHeaders(base, forwarded, staticHeaders) {
+  const out = {};
+  const apply = (headers) => {
+    for (const [name, value] of Object.entries(headers)) {
+      out[name.toLowerCase()] = value;
+    }
+  };
+  apply(base);
+  apply(forwarded);
+  apply(staticHeaders);
+  return out;
+}
+
 // src/upstream/connection-error.ts
 var UPSTREAM_DOCS_URL = "https://github.com/gethelio/helio/blob/main/docs/getting-started.md";
 var UNREACHABLE_CODES = /* @__PURE__ */ new Set([
@@ -1131,26 +1235,325 @@ function describeUnreachableUpstream(error, url) {
   );
 }
 
-// src/upstream/forwarder.ts
-var UpstreamForwarder = class {
+// src/upstream/upstream-session-manager.ts
+var HELIO_MCP_PROTOCOL_VERSION = "2025-06-18";
+var MAX_SSE_ERROR_SCAN_BYTES = 256 * 1024;
+var UpstreamSessionManager = class {
+  url;
+  staticHeaders;
+  requestTimeoutMs;
+  internal;
+  inflight;
+  constructor(options) {
+    this.url = options.url;
+    this.staticHeaders = options.staticHeaders;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
+  }
+  /** Return the internal session, performing the handshake once if needed. */
+  ensureInternalSession() {
+    if (this.internal) return Promise.resolve(this.internal);
+    this.inflight ??= this.initialize().then((session) => {
+      this.internal = session;
+      return session;
+    }).finally(() => {
+      this.inflight = void 0;
+    });
+    return this.inflight;
+  }
+  /**
+   * Drop the cached internal session so the next call re-initializes.
+   * Does not cancel any in-flight initialize.
+   */
+  invalidateInternalSession() {
+    this.internal = void 0;
+  }
+  /** Convert a fetch failure into an actionable error for the given step. */
+  describeFetchFailure(error, step) {
+    if (error instanceof Error && error.name === "TimeoutError") {
+      return new Error(`upstream ${step} timed out after ${String(this.requestTimeoutMs)}ms`);
+    }
+    return describeUnreachableUpstream(error, this.url) ?? (error instanceof Error ? error : new Error(String(error)));
+  }
+  async initialize() {
+    const headers = mergeUpstreamHeaders(
+      {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream"
+      },
+      {},
+      this.staticHeaders
+    );
+    const initBody = {
+      jsonrpc: "2.0",
+      id: 0,
+      method: "initialize",
+      params: {
+        protocolVersion: HELIO_MCP_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "helio-proxy", version: "0" }
+      }
+    };
+    let res;
+    try {
+      res = await fetch(this.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(initBody),
+        signal: AbortSignal.timeout(this.requestTimeoutMs)
+      });
+    } catch (error) {
+      throw this.describeFetchFailure(error, "initialize");
+    }
+    if (!res.ok) {
+      throw new Error(`upstream initialize failed: HTTP ${String(res.status)}`);
+    }
+    const sessionId = res.headers.get("mcp-session-id") ?? void 0;
+    const initializeEnvelope = await this.readRequiredJsonRpcEnvelope(
+      res,
+      initBody.id,
+      "initialize"
+    );
+    const initializeError = extractJsonRpcErrorMessage(initializeEnvelope);
+    if (initializeError) {
+      throw new Error(`upstream initialize returned JSON-RPC error: ${initializeError}`);
+    }
+    const negotiatedProtocolVersion = extractNegotiatedProtocolVersion(initializeEnvelope);
+    const notifyHeaders = { ...headers };
+    if (sessionId) notifyHeaders["mcp-session-id"] = sessionId;
+    notifyHeaders["mcp-protocol-version"] = negotiatedProtocolVersion;
+    const notifyRes = await fetch(this.url, {
+      method: "POST",
+      headers: notifyHeaders,
+      body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
+      signal: AbortSignal.timeout(this.requestTimeoutMs)
+    }).catch((error) => {
+      throw this.describeFetchFailure(error, "notifications/initialized");
+    });
+    if (!notifyRes.ok) {
+      throw new Error(`upstream notifications/initialized failed: HTTP ${String(notifyRes.status)}`);
+    }
+    const notifyError = await this.readOptionalJsonRpcError(notifyRes);
+    if (notifyError) {
+      throw new Error(`upstream notifications/initialized returned JSON-RPC error: ${notifyError}`);
+    }
+    return { sessionId, protocolVersion: negotiatedProtocolVersion };
+  }
+  async readRequiredJsonRpcEnvelope(res, requestId, step) {
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("text/event-stream")) {
+      const payload = await readSseJsonRpcResponse(res, requestId);
+      return payload;
+    }
+    const raw = await res.text();
+    if (!raw.trim()) {
+      throw new Error(`upstream ${step} returned an empty body`);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error(`upstream ${step} returned non-JSON body`);
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new Error(`upstream ${step} returned non-object JSON`);
+    }
+    return parsed;
+  }
+  async readOptionalJsonRpcError(res) {
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("text/event-stream")) {
+      if (!res.body) return void 0;
+      let errorMessage;
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let state = { event: "", data: "", remainder: "" };
+      let scannedBytes = 0;
+      const deadline = Date.now() + this.requestTimeoutMs;
+      const onEvent = (event, data) => {
+        if (errorMessage) return;
+        if (event && event !== "message") return;
+        let parsed2;
+        try {
+          parsed2 = JSON.parse(data);
+        } catch {
+          return;
+        }
+        if (typeof parsed2 !== "object" || parsed2 === null) return;
+        errorMessage = extractJsonRpcErrorMessage(parsed2);
+      };
+      for (; ; ) {
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+          await reader.cancel().catch(() => void 0);
+          throw new Error(
+            `upstream notifications/initialized SSE response timed out after ${String(this.requestTimeoutMs)}ms`
+          );
+        }
+        let chunk;
+        try {
+          chunk = await readSseChunkWithTimeout(reader, remainingMs);
+        } catch {
+          await reader.cancel().catch(() => void 0);
+          throw new Error(
+            `upstream notifications/initialized SSE response timed out after ${String(this.requestTimeoutMs)}ms`
+          );
+        }
+        const { done, value } = chunk;
+        if (value !== void 0) {
+          scannedBytes += value.byteLength;
+          if (scannedBytes > MAX_SSE_ERROR_SCAN_BYTES) {
+            await reader.cancel().catch(() => void 0);
+            throw new Error(
+              `upstream notifications/initialized SSE response exceeded ${String(MAX_SSE_ERROR_SCAN_BYTES)} bytes`
+            );
+          }
+          state = parseSseChunk(decoder.decode(value, { stream: true }), state, onEvent);
+          if (errorMessage) {
+            await reader.cancel().catch(() => void 0);
+            return errorMessage;
+          }
+        }
+        if (done) {
+          const tail = decoder.decode();
+          if (tail) {
+            state = parseSseChunk(tail, state, onEvent);
+          }
+          return errorMessage;
+        }
+      }
+    }
+    const raw = await res.text();
+    if (!raw.trim()) return void 0;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return void 0;
+    }
+    if (typeof parsed !== "object" || parsed === null) return void 0;
+    return extractJsonRpcErrorMessage(parsed);
+  }
+};
+async function readSseChunkWithTimeout(reader, timeoutMs) {
+  let timeoutHandle;
+  try {
+    const result = await Promise.race([
+      reader.read(),
+      new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => {
+          reject(new Error(`sse read timed out after ${String(timeoutMs)}ms`));
+        }, timeoutMs);
+      })
+    ]);
+    if (!isSseReadChunk(result)) {
+      throw new Error("upstream notifications/initialized SSE response returned invalid chunk");
+    }
+    return result;
+  } finally {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+  }
+}
+function isSseReadChunk(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  if (typeof candidate.done !== "boolean") return false;
+  if (candidate.value === void 0) return true;
+  return candidate.value instanceof Uint8Array;
+}
+function extractJsonRpcErrorMessage(payload) {
+  const error = payload["error"];
+  if (typeof error === "string") return error;
+  if (typeof error !== "object" || error === null) return void 0;
+  const message = error["message"];
+  if (typeof message === "string" && message.trim()) return message;
+  return "unknown JSON-RPC error";
+}
+function extractNegotiatedProtocolVersion(payload) {
+  const result = payload["result"];
+  if (typeof result !== "object" || result === null) {
+    return HELIO_MCP_PROTOCOL_VERSION;
+  }
+  const protocolVersion = result["protocolVersion"];
+  return typeof protocolVersion === "string" && protocolVersion.trim() ? protocolVersion : HELIO_MCP_PROTOCOL_VERSION;
+}
+
+// src/upstream/streamable-http-forwarder.ts
+var StreamableHttpForwarder = class {
   url;
   staticHeaders;
   requestTimeoutMs;
+  sessions;
   constructor(options) {
     this.url = options.url;
     this.staticHeaders = options.headers ?? {};
     this.requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
+    this.sessions = new UpstreamSessionManager({
+      url: this.url,
+      staticHeaders: this.staticHeaders,
+      requestTimeoutMs: this.requestTimeoutMs
+    });
+  }
+  /** Lifecycle parity with sse/stdio. No eager connect — sessions are lazy. */
+  connect() {
+    return Promise.resolve();
+  }
+  /** Lifecycle parity with sse/stdio. */
+  close() {
+    this.sessions.invalidateInternalSession();
+    return Promise.resolve();
   }
   async forward(request) {
-    const requestHeaders = request.headers ?? {};
-    const headers = {
-      "content-type": "application/json",
-      accept: "application/json, text/event-stream",
-      ...this.staticHeaders,
-      ...requestHeaders
-    };
-    if (request.sessionId) {
-      headers["mcp-session-id"] = request.sessionId;
+    if (request.method === "initialize") {
+      return this.send(
+        request,
+        request.sessionId,
+        /* protocolVersion */
+        void 0
+      );
+    }
+    return this.send(request, request.sessionId, HELIO_MCP_PROTOCOL_VERSION);
+  }
+  /**
+   * Helio-internal execution path (startup prime / internal maintenance) that
+   * may borrow the proxy-managed internal session.
+   */
+  async forwardInternal(request) {
+    const session = await this.sessions.ensureInternalSession();
+    try {
+      return await this.send(
+        request,
+        session.sessionId,
+        session.protocolVersion,
+        /* internalManaged */
+        true
+      );
+    } catch (error) {
+      if (error instanceof UpstreamSessionExpiredError) {
+        this.sessions.invalidateInternalSession();
+        const fresh = await this.sessions.ensureInternalSession();
+        return this.send(
+          request,
+          fresh.sessionId,
+          fresh.protocolVersion,
+          /* internalManaged */
+          true
+        );
+      }
+      throw error;
+    }
+  }
+  async send(request, sessionId, protocolVersion, internalManaged = false) {
+    const headers = mergeUpstreamHeaders(
+      {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream"
+      },
+      request.headers ?? {},
+      this.staticHeaders
+    );
+    if (sessionId) headers["mcp-session-id"] = sessionId;
+    if (protocolVersion && headers["mcp-protocol-version"] === void 0) {
+      headers["mcp-protocol-version"] = protocolVersion;
     }
     const body = {
       jsonrpc: request.jsonrpc,
@@ -1164,34 +1567,53 @@ var UpstreamForwarder = class {
     const signal = requestSignal ? AbortSignal.any([requestSignal, timeoutSignal]) : timeoutSignal;
     let res;
     try {
-      res = await fetch(this.url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-        signal
-      });
+      res = await fetch(this.url, { method: "POST", headers, body: JSON.stringify(body), signal });
     } catch (error) {
       const isTimeout = error instanceof Error && error.name === "TimeoutError";
-      if (requestSignal?.aborted) {
-        throw new Error("request aborted by downstream client");
-      }
+      if (requestSignal?.aborted) throw new Error("request aborted by downstream client");
       if (isTimeout) {
         throw new Error(`upstream request timed out after ${String(this.requestTimeoutMs)}ms`);
       }
       throw describeUnreachableUpstream(error, this.url) ?? error;
     }
-    const durationMs = performance.now() - start;
+    if (internalManaged && res.status === 404 && sessionId) {
+      await res.text().catch(() => void 0);
+      throw new UpstreamSessionExpiredError();
+    }
     const contentType = res.headers.get("content-type") ?? "";
     if (contentType.includes("text/event-stream")) {
-      throw new Error(
-        "upstream returned text/event-stream; streamable-http passthrough is not supported in v0.1"
-      );
+      const responseHeaders = {};
+      res.headers.forEach((value, key) => {
+        responseHeaders[key] = value;
+      });
+      if (request.id === void 0) {
+        await res.body?.cancel().catch(() => void 0);
+        const response3 = {
+          status: res.status,
+          headers: responseHeaders,
+          body: { jsonrpc: "2.0" }
+        };
+        return { response: response3, durationMs: performance.now() - start };
+      }
+      const jsonRpc = await readSseJsonRpcResponse(res, request.id);
+      const response2 = { status: res.status, headers: responseHeaders, body: jsonRpc };
+      return { response: response2, durationMs: performance.now() - start };
     }
     const response = await parseUpstreamResponse(res);
-    return { response, durationMs };
+    return { response, durationMs: performance.now() - start };
+  }
+};
+var UpstreamSessionExpiredError = class extends Error {
+  constructor() {
+    super("upstream session expired (HTTP 404) for Helio-managed internal session");
+    this.name = "UpstreamSessionExpiredError";
   }
 };
 
+// src/upstream/forwarder.ts
+var UpstreamForwarder = class extends StreamableHttpForwarder {
+};
+
 // src/mcp/pending-requests.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var PendingRequests = class {
@@ -1261,26 +1683,6 @@ function buildRequestSignal(request, timeoutMs) {
   const timeoutSignal = AbortSignal.timeout(timeoutMs);
   return request.signal ? AbortSignal.any([request.signal, timeoutSignal]) : timeoutSignal;
 }
-function parseSseChunk(chunk, state, onEvent) {
-  let { event, data, remainder } = state;
-  const text = remainder + chunk;
-  const lines = text.split("\n");
-  remainder = lines.pop() ?? "";
-  for (const line of lines) {
-    if (line === "") {
-      if (event || data) {
-        onEvent(event, data);
-        event = "";
-        data = "";
-      }
-    } else if (line.startsWith("event: ")) {
-      event = line.slice(7);
-    } else if (line.startsWith("data: ")) {
-      data = data ? data + "\n" + line.slice(6) : line.slice(6);
-    }
-  }
-  return { event, data, remainder };
-}
 var SseUpstreamForwarder = class {
   url;
   staticHeaders;
@@ -1354,12 +1756,11 @@ var SseUpstreamForwarder = class {
     };
     if (request.id !== void 0) body["id"] = request.id;
     if (request.params !== void 0) body["params"] = request.params;
-    const requestHeaders = request.headers ?? {};
-    const headers = {
-      "content-type": "application/json",
-      ...this.staticHeaders,
-      ...requestHeaders
-    };
+    const headers = mergeUpstreamHeaders(
+      { "content-type": "application/json" },
+      request.headers ?? {},
+      this.staticHeaders
+    );
     if (request.sessionId) {
       headers["mcp-session-id"] = request.sessionId;
     }
@@ -2127,6 +2528,11 @@ var GovernedForwarder = class {
    *
    * This path is intended for startup warm-up and intentionally bypasses policy
    * and audit handling. Runtime tools/list requests still flow through forward().
+   *
+   * When the inner forwarder exposes `forwardInternal` (duck-typed), the prime
+   * request is routed through it so session-enforcing servers (e.g. Streamable
+   * HTTP upstreams) receive the request on the managed internal session rather
+   * than as a sessionless call that they would reject with HTTP 400.
    */
   async primeAnnotationCache() {
     const syntheticToolsList = {
@@ -2134,14 +2540,22 @@ var GovernedForwarder = class {
       id: "helio-prime-annotations",
       method: "tools/list"
     };
+    const internal = this.inner;
     try {
-      const result = await this.inner.forward(syntheticToolsList);
+      const result = typeof internal.forwardInternal === "function" ? await internal.forwardInternal(syntheticToolsList) : await this.inner.forward(syntheticToolsList);
+      if (result.response.status >= 400) {
+        return {
+          success: false,
+          toolsCached: this.annotationCache.size,
+          reason: classifyPrimeFailure(result.response)
+        };
+      }
       const updated = this.annotationCache.update(result.response.body);
       if (!updated) {
         return {
           success: false,
           toolsCached: this.annotationCache.size,
-          reason: "upstream tools/list response had unexpected shape"
+          reason: classifyPrimeFailure(result.response)
         };
       }
       return { success: true, toolsCached: this.annotationCache.size };
@@ -2742,6 +3156,27 @@ function hasJsonRpcError(result) {
   const body = result.response.body;
   return body?.["error"] !== void 0;
 }
+function classifyPrimeFailure(response) {
+  if (response.status >= 400) {
+    return `upstream returned HTTP ${String(response.status)} to tools/list (session/initialize may be required)`;
+  }
+  const rawBody = response.body;
+  if (typeof rawBody !== "object" || rawBody === null) {
+    return `upstream tools/list returned a non-JSON body (content-type ${response.headers["content-type"] ?? "unknown"})`;
+  }
+  const body = rawBody;
+  const error = body["error"];
+  if (typeof error === "string") {
+    return `upstream tools/list returned a JSON-RPC error: ${error}`;
+  }
+  if (error !== null && typeof error === "object") {
+    const message = error["message"];
+    if (typeof message === "string") {
+      return `upstream tools/list returned a JSON-RPC error: ${message}`;
+    }
+  }
+  return "upstream tools/list response was missing result.tools";
+}
 function extractBlockReason(result) {
   const body = result.response.body;
   const error = body?.["error"];
@@ -5694,6 +6129,7 @@ export {
   SpendLimiter,
   SseUpstreamForwarder,
   StdioForwarder,
+  StreamableHttpForwarder,
   UpstreamForwarder,
   VERSION,
   WebhookChannel,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethelio/proxy",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "Open-source MCP governance proxy for AI agents",
   "license": "Apache-2.0",