@stage-labs/metro 0.1.0-beta.120 → 0.1.0-beta.121

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.120",
+  "version": "0.1.0-beta.121",
   "description": "The metro command line. Sign in once per machine, then hand your MCP connector list to Claude Code without the credentials touching disk, argv or shell history.",
   "license": "MIT",
   "repository": {

package/runtime/marketplace/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "metro",
-  "version": "0.1.0-beta.120",
+  "version": "0.1.0-beta.121",
   "description": "Metro for Claude Code, installed by the metro daemon on this machine: every connector the agent holds as its own MCP server relayed through the daemon, the orchestrator-only guard on the main thread, the standing rules loaded at each session start, and a refresh skill for when the daemon could not keep the server list current. No vendor credential ever sits in a config file.",
   "author": {
     "name": "Bonustrack",

package/runtime/node_modules/@metro-labs/daemon/src/connectors/oauth-client.ts

@@ -1,4 +1,5 @@
 import { createHash, randomBytes } from 'node:crypto';
+import { whyUnreachable } from './reach.js';
 import {
   ConnectorVerifyError,
   type OAuthTokens,
@@ -51,8 +52,8 @@ export async function registerClient(
         token_endpoint_auth_method: 'none',
       }),
     });
-  } catch {
-    throw refused('Metro could not reach that server to register.');
+  } catch (err) {
+    throw refused(`Metro could not reach that server to register: ${whyUnreachable(err)}`);
   }
   const body: unknown = await res.json().catch(() => null);
   if (!res.ok || !isRecord(body) || typeof body.client_id !== 'string')
@@ -126,8 +127,8 @@ async function postToken(
       },
       body: params.toString(),
     });
-  } catch {
-    throw refused('Metro could not reach that server to finish signing in.');
+  } catch (err) {
+    throw refused(`Metro could not reach that server to finish signing in: ${whyUnreachable(err)}`);
   }
   const body: unknown = await res.json().catch(() => null);
   if (!res.ok || !isRecord(body))

package/runtime/node_modules/@metro-labs/daemon/src/connectors/reach.ts

@@ -0,0 +1,27 @@
+import { errMsg } from '@metro-labs/core/log';
+
+const HINTS: Record<string, string> = {
+  ENOTFOUND: 'the name does not resolve',
+  EAI_AGAIN: 'the name did not resolve in time',
+  ECONNREFUSED: 'nothing is listening there',
+  ECONNRESET: 'the server dropped the connection',
+  ETIMEDOUT: 'the server did not answer in time',
+  ConnectionRefused: 'nothing is listening there',
+  CERT_HAS_EXPIRED: 'its certificate has expired',
+  DEPTH_ZERO_SELF_SIGNED_CERT: 'its certificate is self-signed',
+  UNABLE_TO_VERIFY_LEAF_SIGNATURE: 'its certificate could not be verified',
+  ERR_TLS_CERT_ALTNAME_INVALID: 'its certificate is for another name',
+  SELF_SIGNED_CERT_IN_CHAIN: 'its certificate chain is not trusted',
+};
+
+const codeOf = (err: unknown): string =>
+  err !== null && typeof err === 'object' && 'code' in err && typeof err.code === 'string' ? err.code : '';
+
+export function whyUnreachable(err: unknown): string {
+  const inner = err instanceof Error && err.cause instanceof Error ? err.cause : err;
+  const message = errMsg(inner).trim();
+  const code = codeOf(inner) || codeOf(err);
+  const said = message !== '' && message !== 'fetch failed' ? message : code || 'no answer';
+  const hint = HINTS[code];
+  return hint === undefined ? said : `${said} (${hint})`;
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/relay.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { whyUnreachable } from './reach.js';
 import type { RelayTarget } from './relay-target.js';
 import type { AgentIdentity } from '@metro-labs/http/api-http';
 import { ApiError } from '@metro-labs/http/api-error';
@@ -267,7 +268,7 @@ function dispatch(
         answer(res, err.status, { error: err.message });
       } else {
         log.warn({ err: errMsg(err), connector: connectorId }, 'relay: failed');
-        answer(res, 502, { error: 'metro could not reach the connector' });
+        answer(res, 502, { error: `metro could not reach the connector: ${whyUnreachable(err)}` });
         if (!res.writableEnded) res.end();
       }
       closeIfBodyUnread(req, res);

package/runtime/node_modules/@metro-labs/daemon/src/connectors/verify.ts

@@ -1,4 +1,5 @@
 import { errMsg, log } from '@metro-labs/core/log';
+import { whyUnreachable } from './reach.js';
 import {
   ConnectorNotMcp,
   ConnectorUnauthorized,
@@ -97,8 +98,8 @@ async function frame(
       },
       body: JSON.stringify(body),
     });
-  } catch {
-    throw refused(`Metro could not reach ${url.hostname}.`);
+  } catch (err) {
+    throw refused(`Metro could not reach ${url.hostname}: ${whyUnreachable(err)}`);
   }
   if (res.status >= 300 && res.status < 400) {
     await discard(res);

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.120"
+  "version": "0.1.0-beta.121"
 }