@gethelio/proxy 0.1.0 → 0.2.0

package/README.md

@@ -249,20 +249,19 @@ Every tool call recorded: timestamp, agent identity, tool name, inputs, policy d
 
 ## How Helio Compares
 
-|                                     | Helio                 | Guild.ai          | JetStream       | Cerbos          | Salus          |
-| ----------------------------------- | --------------------- | ----------------- | --------------- | --------------- | -------------- |
-| **Approach**                        | Proxy + thin SDK      | Platform runtime  | Enterprise SaaS | Sidecar library | In-process SDK |
-| **Requires migration**              | No                    | Yes               | No              | No              | Code changes   |
-| **Time to value**                   | 5 minutes             | Weeks             | Weeks           | Hours           | Minutes        |
-| **Open source**                     | ✅ Apache 2.0         | ❌                | ❌              | ✅ Apache 2.0   | ❌             |
-| **Evidence grounding**              | ✅                    | ❌                | ❌              | ❌              | ✅             |
-| **Self-repair feedback**            | ✅                    | ❌                | ❌              | ❌              | ✅             |
-| **Approval workflows**              | ✅                    | ✅ (in runtime)   | ✅              | ❌              | ❌             |
-| **Transaction controls**            | ✅ \*                 | Basic             | Cost tracking   | ❌              | ❌             |
-| **Audit trail**                     | ✅ (incl. downstream) | ✅ (runtime only) | ✅              | Decision logs   | ❌             |
-| **Cross-platform**                  | ✅ Any MCP agent      | ❌ Guild only     | ✅              | ✅              | ✅ Python only |
-| **Governs agents you didn't build** | ✅                    | ❌                | ✅              | ✅              | ❌             |
-| **Language agnostic**               | ✅ (proxy)            | ✅                | ✅              | ✅              | ❌ Python only |
+|                                              | Helio                                  | Obot                           | Cerbos                            | Built-in (Anthropic / OpenAI)         | Framework (LangChain / CrewAI)      |
+| -------------------------------------------- | -------------------------------------- | ------------------------------ | --------------------------------- | ------------------------------------- | ----------------------------------- |
+| **What it governs**                          | Per-call actions with cross-call state | Which tools/MCPs are reachable | App-level authorization decisions | Agent permissions inside one platform | Agent behavior inside one framework |
+| **Architecture**                             | Out-of-process MCP proxy               | Out-of-process MCP gateway     | Sidecar / library                 | In-platform                           | In-framework                        |
+| **Open source**                              | ✅ Apache 2.0                          | ✅ Apache 2.0                  | ✅ Apache 2.0                     | ❌                                    | Varies                              |
+| **Time to value**                            | 5 minutes                              | Setup-dependent                | Hours                             | Built-in                              | Built-in                            |
+| **No agent code changes**                    | ✅                                     | ✅                             | ❌                                | ✅ (within platform)                  | ❌                                  |
+| **Governs agents you didn't build**          | ✅ Any MCP agent                       | ✅ Any MCP agent               | ✅ (any app)                      | ❌ One platform only                  | ❌ One framework only               |
+| **Evidence grounding**                       | ✅ Cumulative across calls             | ❌                             | ❌                                | ❌                                    | Limited                             |
+| **Self-repair feedback**                     | ✅ Structured retry hints              | ❌                             | ❌                                | ❌                                    | Limited                             |
+| **Stateful spend / rate limits**             | ✅ Per-tool, per-session¹              | Basic                          | ❌                                | ❌                                    | Limited                             |
+| **Approval workflows**                       | ✅ Slack, webhook, dashboard           | ✅                             | ❌                                | Limited                               | Limited                             |
+| **Audit trail (incl. downstream responses)** | ✅ Captures upstream MCP responses     | Decision logs                  | Decision logs                     | Platform telemetry                    | Framework logs                      |
 
 \* Per-tool and per-session spend limits ship in v0.1. Cross-tool spend aggregation is planned for v0.2.
 

package/dist/cli.js

@@ -47,7 +47,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"]
@@ -61,6 +62,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),
@@ -1198,6 +1215,59 @@ async function parseUpstreamResponse(res) {
   return { status: res.status, headers, body };
 }
 
+// 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([
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ECONNRESET",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ETIMEDOUT",
+  "EPIPE",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_SOCKET"
+]);
+function extractErrorCode(error) {
+  let current = error;
+  for (let depth = 0; depth < 5 && current != null; depth += 1) {
+    if (typeof current === "object" && "code" in current) {
+      const code = current.code;
+      if (typeof code === "string") return code;
+    }
+    current = current.cause;
+  }
+  return void 0;
+}
+function describeUnreachableUpstream(error, url) {
+  const code = extractErrorCode(error);
+  const isGenericFetchFailure = error instanceof TypeError && error.message === "fetch failed";
+  if (code !== void 0) {
+    if (!UNREACHABLE_CODES.has(code)) return null;
+  } else if (!isGenericFetchFailure) {
+    return null;
+  }
+  const codeSuffix = code ? ` (${code})` : "";
+  return new Error(
+    `Upstream MCP server at ${url} is unreachable${codeSuffix} \u2014 is it running? Helio proxies an existing MCP server: set upstream.url in helio.yaml to a reachable server, or start the server it points at. See ${UPSTREAM_DOCS_URL}`
+  );
+}
+
+// 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/forwarder.ts
 var UpstreamForwarder = class {
   url;
@@ -1209,13 +1279,14 @@ var UpstreamForwarder = class {
     this.requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
   }
   async forward(request) {
-    const requestHeaders = request.headers ?? {};
-    const headers = {
-      "content-type": "application/json",
-      accept: "application/json, text/event-stream",
-      ...this.staticHeaders,
-      ...requestHeaders
-    };
+    const headers = mergeUpstreamHeaders(
+      {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream"
+      },
+      request.headers ?? {},
+      this.staticHeaders
+    );
     if (request.sessionId) {
       headers["mcp-session-id"] = request.sessionId;
     }
@@ -1245,7 +1316,7 @@ var UpstreamForwarder = class {
       if (isTimeout) {
         throw new Error(`upstream request timed out after ${String(this.requestTimeoutMs)}ms`);
       }
-      throw error;
+      throw describeUnreachableUpstream(error, this.url) ?? error;
     }
     const durationMs = performance.now() - start;
     const contentType = res.headers.get("content-type") ?? "";
@@ -1406,7 +1477,7 @@ var SseUpstreamForwarder = class {
             );
             return;
           }
-          reject(asError);
+          reject(describeUnreachableUpstream(err, this.url) ?? asError);
         }
       });
     });
@@ -1421,12 +1492,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;
     }
@@ -1452,7 +1522,7 @@ var SseUpstreamForwarder = class {
             `upstream notification POST timed out after ${String(this.requestTimeoutMs)}ms`
           );
         }
-        throw asError;
+        throw describeUnreachableUpstream(error, this.postUrl) ?? asError;
       }
       if (!res.ok) {
         throw new Error(`upstream notification POST failed: HTTP ${String(res.status)}`);
@@ -1499,7 +1569,8 @@ var SseUpstreamForwarder = class {
       const asError = error instanceof Error ? error : new Error(String(error));
       const isTimeout = asError.name === "TimeoutError";
       const isAborted = request.signal?.aborted === true;
-      const postFailure = isTimeout ? new Error(`upstream request POST timed out after ${String(this.requestTimeoutMs)}ms`) : asError;
+      const networkFailure = describeUnreachableUpstream(error, this.postUrl) ?? asError;
+      const postFailure = isTimeout ? new Error(`upstream request POST timed out after ${String(this.requestTimeoutMs)}ms`) : networkFailure;
       this.pending.reject(
         requestId,
         isAborted ? new Error("request aborted by downstream client") : postFailure
@@ -1737,6 +1808,40 @@ var StdioForwarder = class {
   }
 };
 
+// src/cli-forwarder.ts
+async function createForwarderFromConfig(config) {
+  switch (config.upstream.transport) {
+    case "streamable-http": {
+      return {
+        forwarder: new UpstreamForwarder({
+          url: config.upstream.url,
+          headers: config.upstream.headers,
+          requestTimeoutMs: parseDuration(config.upstream.request_timeout)
+        })
+      };
+    }
+    case "sse": {
+      const sse = new SseUpstreamForwarder({
+        url: config.upstream.url,
+        headers: config.upstream.headers,
+        connectTimeoutMs: parseDuration(config.upstream.connect_timeout),
+        requestTimeoutMs: parseDuration(config.upstream.request_timeout)
+      });
+      await sse.connect();
+      return { forwarder: sse, close: () => sse.close() };
+    }
+    case "stdio": {
+      const stdio = new StdioForwarder({
+        command: config.upstream.command,
+        args: config.upstream.args,
+        requestTimeoutMs: parseDuration(config.upstream.request_timeout)
+      });
+      await stdio.start();
+      return { forwarder: stdio, close: () => stdio.close() };
+    }
+  }
+}
+
 // src/policy/matchers.ts
 var ANNOTATION_DEFAULTS = {
   readOnlyHint: false,
@@ -5840,6 +5945,8 @@ upstream:
   url: "http://localhost:8080/mcp"
   # Transport: streamable-http (default), sse, or stdio
   transport: streamable-http
+#   headers:
+#     Authorization: "Bearer \${UPSTREAM_TOKEN}"
 
 # Operator dashboard + approval REST API. Bound to 127.0.0.1 by default \u2014 do
 # not change to 0.0.0.0 without putting an authenticating reverse proxy in
@@ -5987,43 +6094,7 @@ async function startCommand(configPath, options) {
     );
     process.exit(1);
   }
-  let forwarder;
-  let closeForwarder;
-  switch (config.upstream.transport) {
-    case "streamable-http": {
-      forwarder = new UpstreamForwarder({
-        url: config.upstream.url,
-        requestTimeoutMs: parseDuration(config.upstream.request_timeout)
-      });
-      break;
-    }
-    case "stdio": {
-      if (!config.upstream.command) {
-        console.error('Error: "command" is required for stdio transport');
-        process.exit(1);
-      }
-      const stdio = new StdioForwarder({
-        command: config.upstream.command,
-        args: config.upstream.args,
-        requestTimeoutMs: parseDuration(config.upstream.request_timeout)
-      });
-      await stdio.start();
-      forwarder = stdio;
-      closeForwarder = () => stdio.close();
-      break;
-    }
-    case "sse": {
-      const sse = new SseUpstreamForwarder({
-        url: config.upstream.url,
-        connectTimeoutMs: parseDuration(config.upstream.connect_timeout),
-        requestTimeoutMs: parseDuration(config.upstream.request_timeout)
-      });
-      await sse.connect();
-      forwarder = sse;
-      closeForwarder = () => sse.close();
-      break;
-    }
-  }
+  const { forwarder, close: closeForwarder } = await createForwarderFromConfig(config);
   const { policy, warnings } = compilePolicies(config.policies);
   for (const w of warnings) {
     const label = w.ruleName ? `rule "${w.ruleName}"` : `rule ${String(w.ruleIndex)}`;