@agentworkspaceos/hermes 0.1.0 → 0.1.1

package/README.md

@@ -10,20 +10,20 @@ Run this command from the machine where Hermes is installed:
 npx --yes @agentworkspaceos/hermes@latest connect \
   --mode plugin \
   --pair AGOS-XXXX-XXXX \
-  --agentos-url https://agentos-local.rewardsbunny.com \
-  --hermes-url http://127.0.0.1:8642 \
-  --dashboard-url http://127.0.0.1:9119
+  --agentos-url http://127.0.0.1:3002
 ```
 
-The connector sends safe runtime metadata and heartbeat status to AgentOS. Secrets stay on the local machine.
+The connector sends safe runtime metadata and heartbeat status to AgentOS. Secrets stay on the local machine. If the dashboard is opened through a browser-only or Cloudflare-protected URL, keep `--agentos-url` pointed at the direct AgentOS API base URL.
+
+When `--hermes-url` is omitted, the CLI probes common local Hermes gateway ports (`8642` through `8645`) and falls back to `http://127.0.0.1:8642`. Use `--hermes-url` when Hermes is running on an unusual local port or a reachable remote gateway. `--dashboard-url` is optional and can be omitted when the Hermes dashboard is not running.
 
 ## Options
 
 ```txt
 agentos-hermes connect --pair <code> [options]
 
---agentos-url <url>    AgentOS web app URL
---hermes-url <url>     Local Hermes gateway URL
+--agentos-url <url>    AgentOS API base URL
+--hermes-url <url>     Local Hermes gateway URL; omitted means auto-detect local Hermes
 --dashboard-url <url>  Optional Hermes dashboard URL
 --mode <mode>          plugin, sidecar, or direct-url
 --config-dir <path>    Local config directory

package/bin/agentos-hermes.js

@@ -4,12 +4,15 @@ import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { homedir, hostname } from "node:os";
 import { dirname, join } from "node:path";
 
-const VERSION = "0.1.0";
+const VERSION = "0.1.1";
 const DEFAULT_AGENTOS_URL = "http://localhost:3000";
 const DEFAULT_HERMES_URL = "http://127.0.0.1:8642";
+const DEFAULT_HERMES_DISCOVERY_PORTS = [8642, 8643, 8644, 8645];
 const DEFAULT_MODE = "plugin";
 const DEFAULT_HERMES_COMMAND = "hermes";
 const HERMES_COMMAND_TIMEOUT_MS = 2500;
+const HERMES_HEALTH_TIMEOUT_MS = 1000;
+const HERMES_DISCOVERY_TIMEOUT_MS = 350;
 const PARENT_AGENT_NAME = "Hermes Main Orchestrator";
 
 async function main(argv) {
@@ -35,7 +38,6 @@ async function main(argv) {
 async function connect(args) {
   const options = parseConnectArgs(args);
   const agentosUrl = normalizeBaseUrl(options.agentosUrl ?? process.env.AGENTOS_URL ?? DEFAULT_AGENTOS_URL);
-  const hermesUrl = normalizeBaseUrl(options.hermesUrl ?? process.env.HERMES_BASE_URL ?? DEFAULT_HERMES_URL);
   const dashboardUrl = options.dashboardUrl ? normalizeBaseUrl(options.dashboardUrl) : undefined;
   const mode = options.mode ?? DEFAULT_MODE;
   const pairingCode = options.pair;
@@ -49,7 +51,9 @@ async function connect(args) {
     throw new Error('--mode must be "plugin", "sidecar", or "direct-url".');
   }
 
-  const hermesHealth = await detectHermes(hermesUrl);
+  const hermesConnection = await resolveHermesConnection(options);
+  const hermesUrl = hermesConnection.hermesUrl;
+  const hermesHealth = hermesConnection.hermesHealth;
   const metadata = options.skipInventory
     ? createFallbackMetadata(hermesHealth)
     : await collectHermesInventory({ hermesCommand, hermesHealth });
@@ -83,6 +87,7 @@ async function connect(args) {
   console.log(`Pairing code: ${session.pairingCode}`);
   console.log(`Status: ${session.status}`);
   console.log(`Mode: ${mode}`);
+  console.log(`Hermes URL: ${hermesUrl}${hermesConnection.autodetected ? " (auto-detected)" : ""}`);
   console.log(`Hermes detected: ${hermesHealth.detected ? "yes" : "no"}`);
   console.log(
     `Inventory: ${metadata.skills?.length ?? 0} skills, ${metadata.toolsets?.length ?? 0} enabled toolsets, ${
@@ -160,13 +165,75 @@ function requireValue(name, value) {
   return value;
 }
 
-async function detectHermes(hermesUrl) {
+async function resolveHermesConnection(options) {
+  const configuredHermesUrl = options.hermesUrl ?? process.env.HERMES_BASE_URL;
+
+  if (configuredHermesUrl) {
+    const hermesUrl = normalizeBaseUrl(configuredHermesUrl);
+    return {
+      autodetected: false,
+      hermesHealth: await detectHermes(hermesUrl),
+      hermesUrl,
+    };
+  }
+
+  const candidates = createHermesDiscoveryUrls();
+  const checks = await Promise.all(
+    candidates.map(async (hermesUrl) => ({
+      hermesHealth: await detectHermes(hermesUrl, { timeoutMs: HERMES_DISCOVERY_TIMEOUT_MS }),
+      hermesUrl,
+    })),
+  );
+  const detected = checks.find((check) => check.hermesHealth.detected);
+
+  if (detected) {
+    return {
+      autodetected: true,
+      ...detected,
+    };
+  }
+
+  const fallbackUrl = normalizeBaseUrl(DEFAULT_HERMES_URL);
+  const fallback = checks.find((check) => check.hermesUrl === fallbackUrl);
+
+  return {
+    autodetected: false,
+    hermesHealth: fallback?.hermesHealth ?? (await detectHermes(fallbackUrl)),
+    hermesUrl: fallbackUrl,
+  };
+}
+
+function createHermesDiscoveryUrls() {
+  const configuredUrls = splitEnvList(process.env.HERMES_DISCOVERY_URLS).map((url) => normalizeBaseUrl(url));
+  const configuredPorts = splitEnvList(process.env.HERMES_DISCOVERY_PORTS)
+    .map((port) => Number(port))
+    .filter((port) => Number.isInteger(port) && port > 0 && port < 65536);
+  const ports = configuredPorts.length ? configuredPorts : DEFAULT_HERMES_DISCOVERY_PORTS;
+  const localUrls = ports.flatMap((port) => [`http://127.0.0.1:${port}`, `http://localhost:${port}`]);
+
+  return [...new Set([...configuredUrls, ...localUrls].map((url) => normalizeBaseUrl(url)))];
+}
+
+function splitEnvList(value) {
+  return value
+    ? value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean)
+    : [];
+}
+
+async function detectHermes(hermesUrl, options = {}) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? HERMES_HEALTH_TIMEOUT_MS);
+
   try {
     const response = await fetch(`${hermesUrl}/health`, {
       headers: {
         accept: "application/json",
       },
       method: "GET",
+      signal: controller.signal,
     });
     const text = await response.text();
     const body = text ? JSON.parse(text) : {};
@@ -182,6 +249,8 @@ async function detectHermes(hermesUrl) {
       platform: null,
       status: "unavailable",
     };
+  } finally {
+    clearTimeout(timeout);
   }
 }
 
@@ -1001,8 +1070,7 @@ async function postHeartbeat(agentosUrl, pairingCode, payload) {
       method: "POST",
     },
   );
-  const text = await response.text();
-  const body = text ? JSON.parse(text) : {};
+  const body = await parseJsonResponse(response, "AgentOS heartbeat endpoint");
 
   if (!response.ok) {
     const message = typeof body.error === "string" ? body.error : `AgentOS returned ${response.status}.`;
@@ -1012,6 +1080,39 @@ async function postHeartbeat(agentosUrl, pairingCode, payload) {
   return body;
 }
 
+async function parseJsonResponse(response, context) {
+  const text = await response.text();
+
+  if (!text) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    const contentType = response.headers.get("content-type") ?? "unknown content type";
+    const status = [response.status, response.statusText].filter(Boolean).join(" ");
+
+    if (isHtmlResponse(text, contentType)) {
+      const isCloudflareChallenge = response.headers.get("cf-mitigated") === "challenge" || text.includes("challenge-platform");
+      const hint = isCloudflareChallenge
+        ? " Cloudflare is challenging the CLI request; use a direct local API URL for --agentos-url, such as http://127.0.0.1:3002, or exempt /api/hermes/* from browser challenges."
+        : " Check that --agentos-url points to the AgentOS API server, not a browser-only app shell or proxy fallback. For local AgentOS, use http://127.0.0.1:3002.";
+
+      throw new Error(context + " returned HTML instead of JSON (" + (status || contentType) + ")." + hint);
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(context + " returned invalid JSON (" + (status || contentType) + "): " + message);
+  }
+}
+
+function isHtmlResponse(text, contentType) {
+  const trimmed = text.trimStart().toLowerCase();
+
+  return contentType.toLowerCase().includes("text/html") || trimmed.startsWith("<!doctype") || trimmed.startsWith("<html");
+}
+
 async function runHeartbeatLoop(sendHeartbeat, intervalMs) {
   if (!Number.isFinite(intervalMs) || intervalMs < 1000) {
     throw new Error("--interval-ms must be at least 1000.");
@@ -1169,9 +1270,9 @@ function printConnectHelp() {
   agentos-hermes connect --pair <code> [options]
 
 Options:
-  --agentos-url <url>  AgentOS web app URL. Defaults to ${DEFAULT_AGENTOS_URL}
-  --hermes-url <url>   Local Hermes gateway URL. Defaults to ${DEFAULT_HERMES_URL}
-  --dashboard-url <url> Optional Hermes dashboard URL, often http://127.0.0.1:9119
+  --agentos-url <url>  AgentOS API base URL. Defaults to ${DEFAULT_AGENTOS_URL}
+  --hermes-url <url>   Local Hermes gateway URL. Defaults to auto-detection, then ${DEFAULT_HERMES_URL}
+  --dashboard-url <url> Optional Hermes dashboard URL. Omit it when the dashboard is not running
   --mode <mode>        plugin, sidecar, or direct-url. Defaults to ${DEFAULT_MODE}
   --config-dir <path>  Local config directory. Defaults to ~/.agentos/hermes
   --hermes-command <cmd> Hermes CLI executable. Defaults to ${DEFAULT_HERMES_COMMAND}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentworkspaceos/hermes",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AgentOS connector CLI for pairing a local Hermes runtime with an AgentOS workspace.",
   "type": "module",
   "bin": {