@agentworkspaceos/hermes 0.1.1 → 0.1.2

package/README.md

@@ -17,6 +17,23 @@ The connector sends safe runtime metadata and heartbeat status to AgentOS. Secre
 
 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
@@ -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,16 @@
 #!/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.1";
+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;
@@ -28,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.`);
   }
@@ -43,13 +49,7 @@ async function connect(args) {
   const pairingCode = options.pair;
   const hermesCommand = options.hermesCommand ?? process.env.HERMES_CLI_COMMAND ?? DEFAULT_HERMES_COMMAND;
 
-  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".');
-  }
+  validateConnectInput({ mode, pairingCode });
 
   const hermesConnection = await resolveHermesConnection(options);
   const hermesUrl = hermesConnection.hermesUrl;
@@ -111,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 = {};
 
@@ -157,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}.`);
@@ -165,6 +336,160 @@ function requireValue(name, value) {
   return value;
 }
 
+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;
 
@@ -1262,6 +1587,7 @@ Usage:
 
 Commands:
   connect    Pair the local Hermes agent with AgentOS
+  service    Install or remove a background connector service
 `);
 }
 
@@ -1282,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.1",
+  "version": "0.1.2",
   "description": "AgentOS connector CLI for pairing a local Hermes runtime with an AgentOS workspace.",
   "type": "module",
   "bin": {