@agentworkspaceos/hermes 0.1.0 → 0.1.2

package/README.md

@@ -10,20 +10,37 @@ 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.
+
+## Background Service
+
+On macOS, install the connector as a LaunchAgent so it keeps running after the terminal closes and restarts if it exits:
+
+```sh
+npx --yes @agentworkspaceos/hermes@latest service install \
+  --mode plugin \
+  --pair AGOS-XXXX-XXXX \
+  --agentos-url https://agentos-local.rewardsbunny.com
+```
+
+Logs are written to `~/.agentos/hermes/logs/connector.log`. Remove the service with:
+
+```sh
+npx --yes @agentworkspaceos/hermes@latest service uninstall
+```
 
 ## 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
@@ -33,6 +50,11 @@ agentos-hermes connect --pair <code> [options]
 --once                 Send one heartbeat and exit
 ```
 
+```txt
+agentos-hermes service install --pair <code> --agentos-url <url> [options]
+agentos-hermes service uninstall [options]
+```
+
 ## Publish
 
 The package is configured for public scoped publishing:
@@ -42,4 +64,4 @@ npm login
 npm publish --access public
 ```
 
-You must own or have publish access to the `@agentos` npm scope before publishing.
+You must own or have publish access to the `@agentworkspaceos` npm scope before publishing.

package/bin/agentos-hermes.js

@@ -1,15 +1,19 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, unlink, 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.2";
 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 DEFAULT_SERVICE_LABEL = "com.agentos.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) {
@@ -25,6 +29,11 @@ async function main(argv) {
     return;
   }
 
+  if (command === "service") {
+    await service(args);
+    return;
+  }
+
   if (command !== "connect") {
     throw new Error(`Unknown command "${command}". Run agentos-hermes --help.`);
   }
@@ -35,21 +44,16 @@ 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;
   const hermesCommand = options.hermesCommand ?? process.env.HERMES_CLI_COMMAND ?? DEFAULT_HERMES_COMMAND;
 
-  if (!pairingCode) {
-    throw new Error("Missing --pair <code>.");
-  }
+  validateConnectInput({ mode, pairingCode });
 
-  if (!["plugin", "sidecar", "direct-url"].includes(mode)) {
-    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, ${
@@ -106,6 +111,87 @@ async function connect(args) {
   await runHeartbeatLoop(sendHeartbeat, intervalMs);
 }
 
+async function service(args) {
+  const [subcommand, ...subcommandArgs] = args;
+
+  if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+    printServiceHelp();
+    return;
+  }
+
+  if (subcommand === "install") {
+    await installService(subcommandArgs);
+    return;
+  }
+
+  if (subcommand === "uninstall") {
+    await uninstallService(subcommandArgs);
+    return;
+  }
+
+  throw new Error(`Unknown service command "${subcommand}". Run agentos-hermes service --help.`);
+}
+
+async function installService(args) {
+  const { connectOptions, serviceOptions } = parseServiceInstallArgs(args);
+  const mode = connectOptions.mode ?? DEFAULT_MODE;
+  const pairingCode = connectOptions.pair;
+
+  validateConnectInput({ mode, pairingCode });
+
+  const serviceConfig = await createServiceConfig(connectOptions, serviceOptions);
+
+  if (process.platform !== "darwin" && !serviceOptions.noLoad) {
+    throw new Error("agentos-hermes service install currently supports macOS launchd. Use --no-load to only write the LaunchAgent plist.");
+  }
+
+  await mkdir(dirname(serviceConfig.plistPath), { recursive: true });
+  await mkdir(dirname(serviceConfig.stdoutPath), { recursive: true });
+  await writeFile(serviceConfig.plistPath, createLaunchAgentPlist(serviceConfig), { mode: 0o644 });
+
+  if (!serviceOptions.noLoad) {
+    await bootoutLaunchAgent(serviceConfig);
+    await bootstrapLaunchAgent(serviceConfig);
+  }
+
+  console.log("AgentOS Hermes background service installed");
+  console.log(`Label: ${serviceConfig.label}`);
+  console.log(`Plist: ${serviceConfig.plistPath}`);
+  console.log(`Logs: ${serviceConfig.stdoutPath}`);
+
+  if (serviceOptions.noLoad) {
+    console.log(`Load it with: launchctl bootstrap gui/$(id -u) ${serviceConfig.plistPath}`);
+  } else {
+    console.log("Status: loaded");
+  }
+}
+
+async function uninstallService(args) {
+  const serviceOptions = parseServiceUninstallArgs(args);
+  const label = serviceOptions.label ?? DEFAULT_SERVICE_LABEL;
+  const launchAgentDir = serviceOptions.launchAgentDir ?? join(homedir(), "Library", "LaunchAgents");
+  const plistPath = join(launchAgentDir, `${label}.plist`);
+  const serviceConfig = { label, plistPath };
+
+  if (process.platform !== "darwin" && !serviceOptions.noLoad) {
+    throw new Error("agentos-hermes service uninstall currently supports macOS launchd. Use --no-load to only remove the LaunchAgent plist.");
+  }
+
+  if (!serviceOptions.noLoad) {
+    await bootoutLaunchAgent(serviceConfig);
+  }
+
+  await unlink(plistPath).catch((error) => {
+    if (error?.code !== "ENOENT") {
+      throw error;
+    }
+  });
+
+  console.log("AgentOS Hermes background service uninstalled");
+  console.log(`Label: ${label}`);
+  console.log(`Plist: ${plistPath}`);
+}
+
 function parseConnectArgs(args) {
   const options = {};
 
@@ -152,6 +238,96 @@ function parseConnectArgs(args) {
   return options;
 }
 
+function parseServiceInstallArgs(args) {
+  const connectOptions = {};
+  const serviceOptions = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    const next = args[index + 1];
+
+    if (arg === "--label") {
+      serviceOptions.label = requireValue(arg, next);
+      index += 1;
+    } else if (arg === "--launch-agent-dir") {
+      serviceOptions.launchAgentDir = requireValue(arg, next);
+      index += 1;
+    } else if (arg === "--npx-path") {
+      serviceOptions.npxPath = requireValue(arg, next);
+      index += 1;
+    } else if (arg === "--no-load") {
+      serviceOptions.noLoad = true;
+    } else if (arg === "--help" || arg === "-h") {
+      printServiceInstallHelp();
+      process.exit(0);
+    } else if (isConnectOptionWithValue(arg)) {
+      connectOptions[connectOptionKey(arg)] = requireValue(arg, next);
+      index += 1;
+    } else if (arg === "--once") {
+      throw new Error("--once cannot be used with service install.");
+    } else if (arg === "--skip-inventory") {
+      connectOptions.skipInventory = true;
+    } else {
+      throw new Error(`Unknown option "${arg}".`);
+    }
+  }
+
+  return { connectOptions, serviceOptions };
+}
+
+function parseServiceUninstallArgs(args) {
+  const options = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    const next = args[index + 1];
+
+    if (arg === "--label") {
+      options.label = requireValue(arg, next);
+      index += 1;
+    } else if (arg === "--launch-agent-dir") {
+      options.launchAgentDir = requireValue(arg, next);
+      index += 1;
+    } else if (arg === "--no-load") {
+      options.noLoad = true;
+    } else if (arg === "--help" || arg === "-h") {
+      printServiceUninstallHelp();
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown option "${arg}".`);
+    }
+  }
+
+  return options;
+}
+
+function isConnectOptionWithValue(arg) {
+  return ["--pair", "--agentos-url", "--hermes-url", "--dashboard-url", "--mode", "--config-dir", "--hermes-command", "--interval-ms"].includes(arg);
+}
+
+function connectOptionKey(arg) {
+  return {
+    "--agentos-url": "agentosUrl",
+    "--config-dir": "configDir",
+    "--dashboard-url": "dashboardUrl",
+    "--hermes-command": "hermesCommand",
+    "--hermes-url": "hermesUrl",
+    "--interval-ms": "intervalMs",
+    "--mode": "mode",
+    "--pair": "pair",
+  }[arg];
+}
+
+function validateConnectInput({ mode, pairingCode }) {
+  if (!pairingCode) {
+    throw new Error("Missing --pair <code>.");
+  }
+
+  if (!["plugin", "sidecar", "direct-url"].includes(mode)) {
+    throw new Error('--mode must be "plugin", "sidecar", or "direct-url".');
+  }
+}
+
 function requireValue(name, value) {
   if (!value || value.startsWith("--")) {
     throw new Error(`Missing value for ${name}.`);
@@ -160,13 +336,229 @@ function requireValue(name, value) {
   return value;
 }
 
-async function detectHermes(hermesUrl) {
+async function createServiceConfig(connectOptions, serviceOptions) {
+  const label = serviceOptions.label ?? DEFAULT_SERVICE_LABEL;
+  const launchAgentDir = serviceOptions.launchAgentDir ?? join(homedir(), "Library", "LaunchAgents");
+  const logDir = join(homedir(), ".agentos", "hermes", "logs");
+  const npxPath = serviceOptions.npxPath ?? (await findNpxExecutable());
+  const programArguments = [
+    npxPath,
+    "--yes",
+    "@agentworkspaceos/hermes@latest",
+    ...buildServiceConnectArgs(connectOptions),
+  ];
+
+  return {
+    label,
+    pathEnvironment: process.env.PATH ?? "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
+    plistPath: join(launchAgentDir, `${label}.plist`),
+    programArguments,
+    stderrPath: join(logDir, "connector.err.log"),
+    stdoutPath: join(logDir, "connector.log"),
+    workingDirectory: homedir(),
+  };
+}
+
+function buildServiceConnectArgs(options) {
+  const args = [
+    "connect",
+    "--mode",
+    options.mode ?? DEFAULT_MODE,
+    "--pair",
+    options.pair,
+    "--agentos-url",
+    normalizeBaseUrl(options.agentosUrl ?? process.env.AGENTOS_URL ?? DEFAULT_AGENTOS_URL),
+  ];
+
+  if (options.hermesUrl) {
+    args.push("--hermes-url", normalizeBaseUrl(options.hermesUrl));
+  }
+
+  if (options.dashboardUrl) {
+    args.push("--dashboard-url", normalizeBaseUrl(options.dashboardUrl));
+  }
+
+  if (options.configDir) {
+    args.push("--config-dir", options.configDir);
+  }
+
+  if (options.hermesCommand) {
+    args.push("--hermes-command", options.hermesCommand);
+  }
+
+  if (options.intervalMs) {
+    args.push("--interval-ms", String(Number(options.intervalMs)));
+  }
+
+  if (options.skipInventory) {
+    args.push("--skip-inventory");
+  }
+
+  return args;
+}
+
+async function findNpxExecutable() {
+  const candidates = [
+    ...splitPathEntries(process.env.PATH).map((entry) => join(entry, "npx")),
+    "/opt/homebrew/bin/npx",
+    "/usr/local/bin/npx",
+    "/usr/bin/npx",
+  ];
+
+  for (const candidate of [...new Set(candidates)]) {
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+      // Keep looking.
+    }
+  }
+
+  return "npx";
+}
+
+function splitPathEntries(value) {
+  return value
+    ? value
+        .split(":")
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+    : [];
+}
+
+function createLaunchAgentPlist(config) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapePlistValue(config.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${config.programArguments.map((argument) => `    <string>${escapePlistValue(argument)}</string>`).join("\n")}
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>WorkingDirectory</key>
+  <string>${escapePlistValue(config.workingDirectory)}</string>
+  <key>StandardOutPath</key>
+  <string>${escapePlistValue(config.stdoutPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapePlistValue(config.stderrPath)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${escapePlistValue(config.pathEnvironment)}</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+function escapePlistValue(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll("\"", "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+async function bootstrapLaunchAgent(config) {
+  const target = launchctlTarget();
+  const result = await runCommand("launchctl", ["bootstrap", target, config.plistPath], { timeoutMs: 10000 });
+
+  if (!result.ok) {
+    throw new Error(`Could not load launchd service: ${result.stderr || result.stdout || "launchctl bootstrap failed"}`);
+  }
+}
+
+async function bootoutLaunchAgent(config) {
+  const target = launchctlTarget();
+  await runCommand("launchctl", ["bootout", target, config.plistPath], { timeoutMs: 10000 });
+}
+
+function launchctlTarget() {
+  const uid = process.getuid?.();
+
+  if (typeof uid !== "number") {
+    throw new Error("Could not determine the current user id for launchctl.");
+  }
+
+  return `gui/${uid}`;
+}
+
+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 +574,8 @@ async function detectHermes(hermesUrl) {
       platform: null,
       status: "unavailable",
     };
+  } finally {
+    clearTimeout(timeout);
   }
 }
 
@@ -1001,8 +1395,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 +1405,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.");
@@ -1161,6 +1587,7 @@ Usage:
 
 Commands:
   connect    Pair the local Hermes agent with AgentOS
+  service    Install or remove a background connector service
 `);
 }
 
@@ -1169,9 +1596,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}
@@ -1181,6 +1608,50 @@ Options:
 `);
 }
 
+function printServiceHelp() {
+  console.log(`Usage:
+  agentos-hermes service install --pair <code> --agentos-url <url> [options]
+  agentos-hermes service uninstall [options]
+
+Commands:
+  install    Install a macOS launchd service that keeps the connector running
+  uninstall  Remove the macOS launchd service
+`);
+}
+
+function printServiceInstallHelp() {
+  console.log(`Usage:
+  agentos-hermes service install --pair <code> --agentos-url <url> [options]
+
+Connector options:
+  --agentos-url <url>  AgentOS API base URL. Defaults to ${DEFAULT_AGENTOS_URL}
+  --hermes-url <url>   Local Hermes gateway URL. Omitted means auto-detect
+  --dashboard-url <url> Optional Hermes dashboard URL
+  --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}
+  --interval-ms <ms>   Heartbeat interval. Defaults to 15000
+  --skip-inventory     Send basic heartbeat metadata only
+
+Service options:
+  --label <label>      LaunchAgent label. Defaults to ${DEFAULT_SERVICE_LABEL}
+  --npx-path <path>    Absolute path to npx for launchd
+  --launch-agent-dir <path> Directory for the plist. Defaults to ~/Library/LaunchAgents
+  --no-load            Write the plist but do not load it
+`);
+}
+
+function printServiceUninstallHelp() {
+  console.log(`Usage:
+  agentos-hermes service uninstall [options]
+
+Options:
+  --label <label>      LaunchAgent label. Defaults to ${DEFAULT_SERVICE_LABEL}
+  --launch-agent-dir <path> Directory containing the plist. Defaults to ~/Library/LaunchAgents
+  --no-load            Remove the plist but do not call launchctl
+`);
+}
+
 main(process.argv.slice(2)).catch((error) => {
   console.error(error instanceof Error ? error.message : error);
   process.exitCode = 1;

package/package.json

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