@gethelio/proxy 0.1.0 → 0.1.1

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

@@ -1198,6 +1198,45 @@ 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/forwarder.ts
 var UpstreamForwarder = class {
   url;
@@ -1245,7 +1284,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 +1445,7 @@ var SseUpstreamForwarder = class {
             );
             return;
           }
-          reject(asError);
+          reject(describeUnreachableUpstream(err, this.url) ?? asError);
         }
       });
     });
@@ -1452,7 +1491,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 +1538,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