@agentworkspaceos/hermes 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @agentworkspaceos/hermes
+
+AgentOS connector CLI for pairing a local Hermes runtime with an AgentOS workspace.
+
+## Usage
+
+Run this command from the machine where Hermes is installed:
+
+```sh
+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
+```
+
+The connector sends safe runtime metadata and heartbeat status to AgentOS. Secrets stay on the local machine.
+
+## Options
+
+```txt
+agentos-hermes connect --pair <code> [options]
+
+--agentos-url <url>    AgentOS web app URL
+--hermes-url <url>     Local Hermes gateway URL
+--dashboard-url <url>  Optional Hermes dashboard URL
+--mode <mode>          plugin, sidecar, or direct-url
+--config-dir <path>    Local config directory
+--hermes-command <cmd> Hermes CLI executable
+--interval-ms <ms>     Heartbeat interval
+--skip-inventory       Send basic heartbeat metadata only
+--once                 Send one heartbeat and exit
+```
+
+## Publish
+
+The package is configured for public scoped publishing:
+
+```sh
+npm login
+npm publish --access public
+```
+
+You must own or have publish access to the `@agentos` npm scope before publishing.

package/bin/agentos-hermes.js

@@ -0,0 +1,1187 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+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 DEFAULT_AGENTOS_URL = "http://localhost:3000";
+const DEFAULT_HERMES_URL = "http://127.0.0.1:8642";
+const DEFAULT_MODE = "plugin";
+const DEFAULT_HERMES_COMMAND = "hermes";
+const HERMES_COMMAND_TIMEOUT_MS = 2500;
+const PARENT_AGENT_NAME = "Hermes Main Orchestrator";
+
+async function main(argv) {
+  const [command, ...args] = argv;
+
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  if (command === "--version" || command === "-v") {
+    console.log(VERSION);
+    return;
+  }
+
+  if (command !== "connect") {
+    throw new Error(`Unknown command "${command}". Run agentos-hermes --help.`);
+  }
+
+  await connect(args);
+}
+
+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>.");
+  }
+
+  if (!["plugin", "sidecar", "direct-url"].includes(mode)) {
+    throw new Error('--mode must be "plugin", "sidecar", or "direct-url".');
+  }
+
+  const hermesHealth = await detectHermes(hermesUrl);
+  const metadata = options.skipInventory
+    ? createFallbackMetadata(hermesHealth)
+    : await collectHermesInventory({ hermesCommand, hermesHealth });
+  const configPath = await persistLocalConfig({
+    agentosUrl,
+    configDir: options.configDir,
+    dashboardUrl,
+    hermesUrl,
+    mode,
+    pairingCode,
+  });
+  const payload = {
+    connectorMode: mode,
+    connectorVersion: VERSION,
+    hermes: {
+      baseUrl: hermesUrl,
+      dashboardUrl,
+      detected: hermesHealth.detected,
+      platform: hermesHealth.platform,
+      status: hermesHealth.status,
+    },
+    machineLabel: hostname(),
+    metadata,
+  };
+
+  const sendHeartbeat = async () => postHeartbeat(agentosUrl, pairingCode, payload);
+  const session = await sendHeartbeat();
+
+  console.log("AgentOS Hermes connector registered");
+  console.log(`Workspace: ${session.workspaceSlug}`);
+  console.log(`Pairing code: ${session.pairingCode}`);
+  console.log(`Status: ${session.status}`);
+  console.log(`Mode: ${mode}`);
+  console.log(`Hermes detected: ${hermesHealth.detected ? "yes" : "no"}`);
+  console.log(
+    `Inventory: ${metadata.skills?.length ?? 0} skills, ${metadata.toolsets?.length ?? 0} enabled toolsets, ${
+      metadata.mcpServers?.length ?? 0
+    } MCP servers, ${metadata.identityFiles?.length ?? 0} identity files, ${metadata.childAgents?.length ?? 0} child agents`,
+  );
+  console.log(`Local config: ${configPath}`);
+  console.log("Secrets stay local. Full skill docs, identity files, and redacted config were sent.");
+  if (session.status === "pending_confirmation") {
+    console.log("Confirm this Hermes runtime in AgentOS before tasks are sent.");
+  }
+
+  if (options.once) {
+    return;
+  }
+
+  const intervalMs = options.intervalMs ?? 15000;
+
+  console.log(`Sending heartbeat every ${Math.round(intervalMs / 1000)}s. Press Ctrl+C to stop.`);
+
+  await runHeartbeatLoop(sendHeartbeat, intervalMs);
+}
+
+function parseConnectArgs(args) {
+  const options = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    const next = args[index + 1];
+
+    if (arg === "--pair") {
+      options.pair = requireValue(arg, next);
+      index += 1;
+    } else if (arg === "--agentos-url") {
+      options.agentosUrl = requireValue(arg, next);
+      index += 1;
+    } else if (arg === "--hermes-url") {
+      options.hermesUrl = requireValue(arg, next);
+      index += 1;
+    } else if (arg === "--dashboard-url") {
+      options.dashboardUrl = requireValue(arg, next);
+      index += 1;
+    } else if (arg === "--mode") {
+      options.mode = requireValue(arg, next);
+      index += 1;
+    } else if (arg === "--config-dir") {
+      options.configDir = requireValue(arg, next);
+      index += 1;
+    } else if (arg === "--hermes-command") {
+      options.hermesCommand = requireValue(arg, next);
+      index += 1;
+    } else if (arg === "--interval-ms") {
+      options.intervalMs = Number(requireValue(arg, next));
+      index += 1;
+    } else if (arg === "--once") {
+      options.once = true;
+    } else if (arg === "--skip-inventory") {
+      options.skipInventory = true;
+    } else if (arg === "--help" || arg === "-h") {
+      printConnectHelp();
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown option "${arg}".`);
+    }
+  }
+
+  return options;
+}
+
+function requireValue(name, value) {
+  if (!value || value.startsWith("--")) {
+    throw new Error(`Missing value for ${name}.`);
+  }
+
+  return value;
+}
+
+async function detectHermes(hermesUrl) {
+  try {
+    const response = await fetch(`${hermesUrl}/health`, {
+      headers: {
+        accept: "application/json",
+      },
+      method: "GET",
+    });
+    const text = await response.text();
+    const body = text ? JSON.parse(text) : {};
+
+    return {
+      detected: response.ok,
+      platform: typeof body.platform === "string" ? body.platform : null,
+      status: typeof body.status === "string" ? body.status : response.ok ? "ok" : "unavailable",
+    };
+  } catch {
+    return {
+      detected: false,
+      platform: null,
+      status: "unavailable",
+    };
+  }
+}
+
+async function collectHermesInventory({ hermesCommand, hermesHealth }) {
+  const [version, status, tools, skills, mcp, profiles, plugins, cron, insights] = await Promise.all([
+    runHermesCommand(hermesCommand, ["version"]),
+    runHermesCommand(hermesCommand, ["status"]),
+    runHermesCommand(hermesCommand, ["tools", "list"]),
+    runHermesCommand(hermesCommand, ["skills", "list"]),
+    runHermesCommand(hermesCommand, ["mcp", "list"]),
+    runHermesCommand(hermesCommand, ["profile", "list"]),
+    runHermesCommand(hermesCommand, ["plugins", "list"]),
+    runHermesCommand(hermesCommand, ["cron", "list"]),
+    runHermesCommand(hermesCommand, ["insights", "--days", "30"]),
+  ]);
+
+  const versionMetadata = parseVersionOutput(version.stdout);
+  const projectPath = parseProjectPath(version.stdout);
+  const statusMetadata = parseStatusOutput(status.stdout);
+  const toolsetsDetailed = parseToolsetsOutput(tools.stdout);
+  const skillCatalog = projectPath ? await readSkillCatalog(projectPath) : [];
+  const skillsDetailed = mergeSkillDetails(parseSkillsOutput(skills.stdout), skillCatalog);
+  const mcpServersDetailed = parseMcpOutput(mcp.stdout);
+  const profilesDetailed = parseProfilesOutput(profiles.stdout);
+  const pluginsDetailed = parsePluginsOutput(plugins.stdout);
+  const cronJobs = parseCronOutput(cron.stdout);
+  const usageInsights = parseInsightsOutput(insights.stdout);
+  const configFiles = await readHermesConfigFiles(hermesCommand);
+  const identityFiles = await readHermesIdentityFiles(hermesCommand, projectPath);
+  const activeProfile = profilesDetailed.find((profile) => profile.active) ?? profilesDetailed[0];
+
+  return compactObject({
+    ...createFallbackMetadata(hermesHealth),
+    ...versionMetadata,
+    ...statusMetadata,
+    configFiles: configFiles.length ? configFiles : undefined,
+    cronJobs: cronJobs.length ? cronJobs : undefined,
+    identityFiles: identityFiles.length ? identityFiles : undefined,
+    insights: usageInsights,
+    mcpServers: mcpServersDetailed.map((server) => server.name),
+    mcpServersDetailed: mcpServersDetailed.length ? mcpServersDetailed : undefined,
+    plugins: pluginsDetailed.length ? pluginsDetailed : undefined,
+    profile: activeProfile?.name ?? statusMetadata.profile ?? "default",
+    profiles: profilesDetailed.length ? profilesDetailed : undefined,
+    skills: skillsDetailed.map((skill) => skill.name),
+    skillsDetailed: skillsDetailed.length ? skillsDetailed : undefined,
+    toolsets: toolsetsDetailed.filter((toolset) => toolset.status === "enabled").map((toolset) => toolset.name),
+    toolsetsDetailed: toolsetsDetailed.length ? toolsetsDetailed : undefined,
+  });
+}
+
+function parseInsightsOutput(output) {
+  if (!output || !/Hermes Insights|Overview|Sessions:/i.test(output)) {
+    return undefined;
+  }
+
+  const clean = stripAnsi(output);
+  const period = clean.match(/^\s*Period:\s+(.+)$/m)?.[1]?.trim();
+  const insights = compactObject({
+    period: sanitizeDisplayString(period),
+    ...parseOverviewMetrics(clean),
+    models: parseInsightsTable(clean, "Models Used", "Platforms", parseModelsRow),
+    platforms: parseInsightsTable(clean, "Platforms", "Top Tools", parsePlatformsRow),
+    topTools: parseInsightsTable(clean, "Top Tools", "Top Skills", parseToolRow),
+    topSkills: parseInsightsTable(clean, "Top Skills", "Activity Patterns", parseSkillRow),
+    weekdayActivity: parseWeekdayActivity(clean),
+    ...parseActivitySummary(clean),
+    notableSessions: parseInsightsTable(clean, "Notable Sessions", undefined, parseNotableSessionRow),
+  });
+
+  return Object.keys(insights).length ? insights : undefined;
+}
+
+function parseOverviewMetrics(output) {
+  return compactObject({
+    activeTime: output.match(/Active time:\s+([^\n]+?)\s{2,}Avg session:/)?.[1]?.trim(),
+    avgMessagesPerSession: parseNumber(output.match(/Avg msgs\/session:\s+([\d,.]+)/)?.[1]),
+    avgSession: output.match(/Avg session:\s+([^\n]+)/)?.[1]?.trim(),
+    inputTokens: parseNumber(output.match(/Input tokens:\s+([\d,]+)/)?.[1]),
+    messages: parseNumber(output.match(/Messages:\s+([\d,]+)/)?.[1]),
+    outputTokens: parseNumber(output.match(/Output tokens:\s+([\d,]+)/)?.[1]),
+    sessions: parseNumber(output.match(/Sessions:\s+([\d,]+)/)?.[1]),
+    totalTokens: parseNumber(output.match(/Total tokens:\s+([\d,]+)/)?.[1]),
+    toolCalls: parseNumber(output.match(/Tool calls:\s+([\d,]+)/)?.[1]),
+    userMessages: parseNumber(output.match(/User messages:\s+([\d,]+)/)?.[1]),
+  });
+}
+
+function parseInsightsTable(output, startLabel, endLabel, rowParser) {
+  const section = sliceInsightsSection(output, startLabel, endLabel);
+
+  if (!section) {
+    return undefined;
+  }
+
+  const rows = section
+    .split("\n")
+    .map((line) => rowParser(line.trim()))
+    .filter(Boolean);
+
+  return rows.length ? rows : undefined;
+}
+
+function sliceInsightsSection(output, startLabel, endLabel) {
+  const startIndex = output.search(new RegExp(escapeRegExp(startLabel), "i"));
+
+  if (startIndex < 0) {
+    return undefined;
+  }
+
+  const sliced = output.slice(startIndex + startLabel.length);
+  const endIndex = endLabel ? sliced.search(new RegExp(escapeRegExp(endLabel), "i")) : -1;
+
+  return (endIndex >= 0 ? sliced.slice(0, endIndex) : sliced)
+    .split("\n")
+    .filter((line) => !/^[\s─]+$/.test(line))
+    .join("\n");
+}
+
+function parseModelsRow(line) {
+  const match = line.match(/^(.+?)\s+([\d,]+)\s+([\d,]+)$/);
+
+  return match
+    ? compactObject({
+        label: sanitizeDisplayString(match[1]),
+        primary: `${parseNumber(match[2]) ?? 0} sessions`,
+        secondary: `${formatCompactNumber(parseNumber(match[3]) ?? 0)} tokens`,
+        value: parseNumber(match[3]),
+      })
+    : undefined;
+}
+
+function parsePlatformsRow(line) {
+  const match = line.match(/^(.+?)\s+([\d,]+)\s+([\d,]+)\s+([\d,]+)$/);
+
+  return match
+    ? compactObject({
+        label: sanitizeDisplayString(match[1]),
+        primary: `${parseNumber(match[2]) ?? 0} sessions`,
+        secondary: `${formatCompactNumber(parseNumber(match[4]) ?? 0)} tokens`,
+        value: parseNumber(match[2]),
+      })
+    : undefined;
+}
+
+function parseToolRow(line) {
+  const match = line.match(/^(.+?)\s+([\d,]+)\s+([\d.]+%)$/);
+
+  return match
+    ? compactObject({
+        label: sanitizeDisplayString(match[1]),
+        primary: `${parseNumber(match[2]) ?? 0} calls`,
+        secondary: match[3],
+        value: parseNumber(match[2]),
+      })
+    : undefined;
+}
+
+function parseSkillRow(line) {
+  const match = line.match(/^(.+?)\s+([\d,]+)\s+([\d,]+)\s+(.+)$/);
+
+  return match
+    ? compactObject({
+        label: sanitizeDisplayString(match[1]),
+        primary: `${parseNumber(match[2]) ?? 0} loads`,
+        secondary: `${parseNumber(match[3]) ?? 0} edits, last used ${sanitizeDisplayString(match[4])}`,
+        value: parseNumber(match[2]),
+      })
+    : undefined;
+}
+
+function parseNotableSessionRow(line) {
+  const match = line.match(/^(.+?)\s{2,}(.+?)\s{2,}\((.+)\)$/);
+
+  return match
+    ? compactObject({
+        label: sanitizeDisplayString(match[1]),
+        primary: sanitizeDisplayString(match[2]),
+        secondary: sanitizeDisplayString(match[3]),
+      })
+    : undefined;
+}
+
+function parseWeekdayActivity(output) {
+  const rows = [...output.matchAll(/^\s*(Mon|Tue|Wed|Thu|Fri|Sat|Sun)\s+[█\s]+\s+([\d,]+)$/gm)].map((match) =>
+    compactObject({
+      label: match[1],
+      value: parseNumber(match[2]),
+    }),
+  );
+
+  return rows.length ? rows : undefined;
+}
+
+function parseActivitySummary(output) {
+  return compactObject({
+    activeDays: parseNumber(output.match(/Active days:\s+([\d,]+)/)?.[1]),
+    bestStreak: output.match(/Best streak:\s+(.+)$/m)?.[1]?.trim(),
+  });
+}
+
+function createFallbackMetadata(hermesHealth) {
+  return {
+    agentName: PARENT_AGENT_NAME,
+    mcpServers: [],
+    profile: "default",
+    runtimeType: "hermes",
+    skills: [],
+    status: hermesHealth.detected ? "online" : "offline",
+    toolsets: [],
+  };
+}
+
+function runHermesCommand(hermesCommand, args) {
+  return runCommand(hermesCommand, args);
+}
+
+function runCommand(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: {
+        ...process.env,
+        COLUMNS: "220",
+        NO_COLOR: "1",
+        TERM: "dumb",
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let settled = false;
+    let stdout = "";
+    let stderr = "";
+
+    const timeout = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      child.kill("SIGTERM");
+      resolve({ ok: false, stdout, stderr: `${stderr}\nTimed out running hermes ${args.join(" ")}`.trim() });
+    }, options.timeoutMs ?? HERMES_COMMAND_TIMEOUT_MS);
+
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      clearTimeout(timeout);
+      resolve({ ok: false, stdout: "", stderr: error.message });
+    });
+    child.on("close", (status) => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      clearTimeout(timeout);
+      resolve({ ok: status === 0, stdout: stripAnsi(stdout), stderr: stripAnsi(stderr) });
+    });
+  });
+}
+
+function parseVersionOutput(output) {
+  const metadata = {};
+  const version = output.match(/Hermes Agent v([^\s]+)/);
+  const pythonVersion = output.match(/^Python:\s+(.+)$/m);
+  const openAiSdkVersion = output.match(/^OpenAI SDK:\s+(.+)$/m);
+
+  if (version) {
+    metadata.version = version[1];
+  }
+
+  if (pythonVersion) {
+    metadata.pythonVersion = pythonVersion[1].trim();
+  }
+
+  if (openAiSdkVersion) {
+    metadata.openAiSdkVersion = openAiSdkVersion[1].trim();
+  }
+
+  return metadata;
+}
+
+function parseProjectPath(output) {
+  const project = output.match(/^Project:\s+(.+)$/m);
+
+  return project ? project[1].trim() : undefined;
+}
+
+async function readSkillCatalog(projectPath) {
+  const python = join(projectPath, "venv", "bin", "python");
+  const script = `
+import json
+from agent.skill_utils import get_external_skills_dirs, iter_skill_index_files
+from tools.skills_tool import (
+    SKILLS_DIR,
+    _EXCLUDED_SKILL_DIRS,
+    _get_category_from_path,
+    _parse_frontmatter,
+    skill_matches_platform,
+)
+skills = []
+seen = set()
+dirs = []
+if SKILLS_DIR.exists():
+    dirs.append(SKILLS_DIR)
+dirs.extend(get_external_skills_dirs())
+for scan_dir in dirs:
+    for skill_md in iter_skill_index_files(scan_dir, "SKILL.md"):
+        if any(part in _EXCLUDED_SKILL_DIRS for part in skill_md.parts):
+            continue
+        try:
+            content = skill_md.read_text(encoding="utf-8")
+            frontmatter, body = _parse_frontmatter(content)
+            if not skill_matches_platform(frontmatter):
+                continue
+            name = str(frontmatter.get("name") or skill_md.parent.name)[:64]
+            if not name or name in seen:
+                continue
+            description = frontmatter.get("description", "")
+            if not description:
+                for line in body.strip().split("\\n"):
+                    line = line.strip()
+                    if line and not line.startswith("#"):
+                        description = line
+                        break
+            skills.append({
+                "name": name,
+                "category": _get_category_from_path(skill_md),
+                "description": description,
+                "path": str(skill_md),
+                "content": content,
+            })
+            seen.add(name)
+        except Exception:
+            continue
+print(json.dumps(skills))
+`.trim();
+  const result = await runCommand(python, ["-c", script], { cwd: projectPath, timeoutMs: 8000 });
+
+  if (!result.ok || !result.stdout) {
+    return [];
+  }
+
+  try {
+    const parsed = JSON.parse(result.stdout);
+
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+
+    return parsed
+      .map((skill) =>
+        compactObject({
+          category: sanitizeDisplayString(skill.category),
+          content: redactSensitiveContent(String(skill.content ?? "")),
+          contentLength: typeof skill.content === "string" ? skill.content.length : undefined,
+          contentRedacted: true,
+          description: sanitizeDisplayString(skill.description, 420),
+          name: sanitizeDisplayString(skill.name),
+          path: redactLocalPath(sanitizeDisplayString(skill.path, 420)),
+        }),
+      )
+      .filter((skill) => skill.name);
+  } catch {
+    return [];
+  }
+}
+
+function mergeSkillDetails(listRows, catalogRows) {
+  const catalogByName = new Map(catalogRows.map((skill) => [skill.name, skill]));
+  const merged = listRows.map((skill) => compactObject({ ...catalogByName.get(skill.name), ...skill }));
+  const seen = new Set(merged.map((skill) => skill.name));
+
+  for (const skill of catalogRows) {
+    if (!seen.has(skill.name)) {
+      merged.push(skill);
+    }
+  }
+
+  return merged;
+}
+
+async function readHermesConfigFiles(hermesCommand) {
+  const configPathResult = await runHermesCommand(hermesCommand, ["config", "path"]);
+  const configPath = configPathResult.stdout.trim();
+
+  if (!configPath) {
+    return [];
+  }
+
+  const files = [];
+  const hermesHome = dirname(configPath);
+
+  await addConfigFile(files, "Default config", configPath);
+
+  try {
+    const profilesDir = join(hermesHome, "profiles");
+    const profiles = await readdir(profilesDir, { withFileTypes: true });
+
+    for (const profile of profiles) {
+      if (!profile.isDirectory()) {
+        continue;
+      }
+
+      await addConfigFile(files, `Profile config: ${profile.name}`, join(profilesDir, profile.name, "config.yaml"));
+    }
+  } catch {
+    // Profiles are optional.
+  }
+
+  return files;
+}
+
+async function readHermesIdentityFiles(hermesCommand, projectPath) {
+  const files = [];
+  const seen = new Set();
+  const configPathResult = await runHermesCommand(hermesCommand, ["config", "path"]);
+  const configPath = configPathResult.stdout.trim();
+
+  if (configPath) {
+    const hermesHome = dirname(configPath);
+    const profilesDir = join(hermesHome, "profiles");
+
+    await addIdentityFile(files, seen, {
+      label: "Default SOUL.md",
+      path: join(hermesHome, "SOUL.md"),
+      profile: "default",
+      type: "soul",
+    });
+    await addIdentityFile(files, seen, {
+      label: "Default AGENTS.md",
+      path: join(hermesHome, "AGENTS.md"),
+      profile: "default",
+      type: "agent-instructions",
+    });
+    await addIdentityFile(files, seen, {
+      label: "Default MEMORY.md",
+      path: join(hermesHome, "MEMORY.md"),
+      profile: "default",
+      type: "memory",
+    });
+    await addIdentityFile(files, seen, {
+      label: "Default .cursorrules",
+      path: join(hermesHome, ".cursorrules"),
+      profile: "default",
+      type: "rules",
+    });
+
+    try {
+      const profiles = await readdir(profilesDir, { withFileTypes: true });
+
+      for (const profile of profiles) {
+        if (!profile.isDirectory()) {
+          continue;
+        }
+
+        await addProfileIdentityFiles(files, seen, profilesDir, profile.name);
+      }
+    } catch {
+      // Profiles are optional.
+    }
+  }
+
+  if (projectPath) {
+    await addIdentityFile(files, seen, {
+      label: "Hermes project AGENTS.md",
+      path: join(projectPath, "AGENTS.md"),
+      type: "project-instructions",
+    });
+    await addIdentityFile(files, seen, {
+      label: "Hermes project SOUL.md",
+      path: join(projectPath, "SOUL.md"),
+      type: "project-soul",
+    });
+    await addIdentityFile(files, seen, {
+      label: "Docker SOUL.md",
+      path: join(projectPath, "docker", "SOUL.md"),
+      type: "docker-soul",
+    });
+  }
+
+  return files;
+}
+
+async function addProfileIdentityFiles(files, seen, profilesDir, profileName) {
+  const profileDir = join(profilesDir, profileName);
+
+  await addIdentityFile(files, seen, {
+    label: `Profile SOUL.md: ${profileName}`,
+    path: join(profileDir, "SOUL.md"),
+    profile: profileName,
+    type: "profile-soul",
+  });
+  await addIdentityFile(files, seen, {
+    label: `Profile AGENTS.md: ${profileName}`,
+    path: join(profileDir, "AGENTS.md"),
+    profile: profileName,
+    type: "agent-instructions",
+  });
+  await addIdentityFile(files, seen, {
+    label: `Profile MEMORY.md: ${profileName}`,
+    path: join(profileDir, "MEMORY.md"),
+    profile: profileName,
+    type: "memory",
+  });
+  await addIdentityFile(files, seen, {
+    label: `Profile .cursorrules: ${profileName}`,
+    path: join(profileDir, ".cursorrules"),
+    profile: profileName,
+    type: "rules",
+  });
+  await addIdentityFile(files, seen, {
+    label: `Profile memory SOUL.md: ${profileName}`,
+    path: join(profileDir, "memory", "SOUL.md"),
+    profile: profileName,
+    type: "memory-soul",
+  });
+  await addIdentityFile(files, seen, {
+    label: `Profile memory AGENTS.md: ${profileName}`,
+    path: join(profileDir, "memory", "AGENTS.md"),
+    profile: profileName,
+    type: "memory-instructions",
+  });
+  await addIdentityFile(files, seen, {
+    label: `Profile memory MEMORY.md: ${profileName}`,
+    path: join(profileDir, "memory", "MEMORY.md"),
+    profile: profileName,
+    type: "memory",
+  });
+}
+
+async function addConfigFile(files, label, path) {
+  try {
+    const content = await readFile(path, "utf8");
+
+    files.push({
+      content: redactSensitiveContent(content),
+      label,
+      path: redactLocalPath(path),
+      redacted: true,
+    });
+  } catch {
+    // Missing or unreadable config files are not fatal to pairing.
+  }
+}
+
+async function addIdentityFile(files, seen, { label, path, profile, type }) {
+  if (seen.has(path)) {
+    return;
+  }
+
+  seen.add(path);
+
+  try {
+    const content = await readFile(path, "utf8");
+
+    files.push(
+      compactObject({
+        content: redactSensitiveContent(content),
+        label,
+        path: redactLocalPath(path),
+        profile,
+        redacted: true,
+        type,
+      }),
+    );
+  } catch {
+    // Missing identity files are expected across Hermes installs.
+  }
+}
+
+function parseStatusOutput(output) {
+  const metadata = {};
+  const model = output.match(/^\s*Model:\s+(.+)$/m);
+  const provider = output.match(/^\s*Provider:\s+(.+)$/m);
+  const terminalBackend = output.match(/^\s*Backend:\s+(.+)$/m);
+  const sudo = output.match(/^\s*Sudo:\s+(.+)$/m);
+  const gatewayStatus = output.match(/\u25c6 Gateway Service[\s\S]*?^\s*Status:\s+(?:\u2713\s*)?(.+)$/m);
+  const scheduledJobs = output.match(/^\s*Jobs:\s+(\d+)\s+active,\s+(\d+)\s+total$/m);
+  const activeSessions = output.match(/^\s*Active:\s+(\d+)\s+session\(s\)$/m);
+
+  if (model) {
+    metadata.model = model[1].trim();
+  }
+
+  if (provider) {
+    metadata.provider = provider[1].trim();
+  }
+
+  if (terminalBackend) {
+    metadata.terminalBackend = terminalBackend[1].trim();
+  }
+
+  if (sudo) {
+    metadata.sudoEnabled = /enabled/i.test(sudo[1]);
+  }
+
+  if (gatewayStatus) {
+    metadata.gatewayStatus = gatewayStatus[1].trim();
+  }
+
+  if (scheduledJobs) {
+    metadata.scheduledJobs = Number(scheduledJobs[2]);
+  }
+
+  if (activeSessions) {
+    metadata.activeSessions = Number(activeSessions[1]);
+  }
+
+  return metadata;
+}
+
+function parseToolsetsOutput(output) {
+  return output
+    .split("\n")
+    .map((line) => line.match(/^\s*[\u2713\u2717]\s+(enabled|disabled)\s+(\S+)\s+(.+)$/))
+    .filter(Boolean)
+    .map((match) => ({
+      label: sanitizeDisplayString(match[3]),
+      name: sanitizeDisplayString(match[2]),
+      status: match[1],
+    }))
+    .filter((toolset) => toolset.name);
+}
+
+function parseSkillsOutput(output) {
+  return parseBoxRows(output)
+    .map((columns) => {
+      const [name, category, source, trust, status] = columns;
+
+      return compactObject({
+        category: sanitizeDisplayString(category),
+        name: sanitizeDisplayString(name),
+        source: sanitizeDisplayString(source),
+        status: sanitizeDisplayString(status),
+        trust: sanitizeDisplayString(trust),
+      });
+    })
+    .filter((skill) => skill.name && skill.name !== "Name");
+}
+
+function parseMcpOutput(output) {
+  if (/No MCP servers configured/i.test(output)) {
+    return [];
+  }
+
+  return parseBoxRows(output)
+    .map((columns) => compactObject({ name: sanitizeDisplayString(columns[0]), status: sanitizeDisplayString(columns[1]), type: sanitizeDisplayString(columns[2]) }))
+    .filter((server) => server.name && server.name !== "Name");
+}
+
+function parseProfilesOutput(output) {
+  return output
+    .split("\n")
+    .map((line) => {
+      const trimmed = line.trim();
+
+      if (!trimmed || /^Profile\s+Model\s+Gateway\s+Alias/i.test(trimmed) || /^[\u2500\s]+$/.test(trimmed)) {
+        return undefined;
+      }
+
+      const active = trimmed.startsWith("\u25c6");
+      const normalized = trimmed.replace(/^\u25c6/, "").trim();
+      const columns = normalized.split(/\s{2,}/).map((column) => sanitizeDisplayString(column));
+
+      if (!columns[0]) {
+        return undefined;
+      }
+
+      return compactObject({
+        active,
+        alias: columns[3] === "\u2014" ? undefined : columns[3],
+        gateway: columns[2] === "\u2014" ? undefined : columns[2],
+        model: columns[1] === "\u2014" ? undefined : columns[1],
+        name: columns[0],
+      });
+    })
+    .filter(Boolean);
+}
+
+function parsePluginsOutput(output) {
+  const plugins = [];
+
+  for (const columns of parseBoxRows(output)) {
+    const [name, status, version, description, source] = columns.map((column) => sanitizeDisplayString(column));
+
+    if (name && name !== "Name") {
+      plugins.push(
+        compactObject({
+          description: sanitizeDisplayString(description, 420),
+          name,
+          source,
+          status,
+          version,
+        }),
+      );
+    }
+  }
+
+  return plugins;
+}
+
+function parseCronOutput(output) {
+  const jobs = [];
+  let current;
+
+  for (const line of output.split("\n")) {
+    const header = line.match(/^\s*([a-f0-9]{12})\s+\[([^\]]+)\]/i);
+
+    if (header) {
+      current = {
+        id: sanitizeDisplayString(header[1]),
+        name: sanitizeDisplayString(header[1]),
+        status: sanitizeDisplayString(header[2]),
+      };
+      jobs.push(current);
+      continue;
+    }
+
+    if (!current) {
+      continue;
+    }
+
+    const field = line.match(/^\s*(Name|Schedule|Next run|Deliver|Script|Last run):\s+(.+)$/);
+    const repeatField = line.match(/^\s*Repeat:\s+(.+)$/);
+    const skillsField = line.match(/^\s*Skills:\s+(.+)$/);
+
+    if (repeatField) {
+      current.repeat = sanitizeDisplayString(repeatField[1]);
+      continue;
+    }
+
+    if (skillsField) {
+      current.skills = skillsField[1]
+        .split(",")
+        .map((skill) => sanitizeDisplayString(skill))
+        .filter(Boolean);
+      continue;
+    }
+
+    if (!field) {
+      continue;
+    }
+
+    const key = field[1];
+    const value = sanitizeDisplayString(field[2]);
+
+    if (key === "Name") {
+      current.name = value;
+    } else if (key === "Schedule") {
+      current.schedule = value;
+    } else if (key === "Next run") {
+      current.nextRun = value;
+    } else if (key === "Deliver") {
+      current.deliverTo = sanitizeDeliveryTarget(value);
+    } else if (key === "Script") {
+      current.script = value;
+    } else if (key === "Last run") {
+      current.lastRun = value;
+    }
+  }
+
+  return jobs.filter((job) => job.id && job.name);
+}
+
+function parseBoxRows(output) {
+  return output
+    .split("\n")
+    .filter((line) => line.trim().startsWith("\u2502"))
+    .map((line) =>
+      line
+        .slice(1, -1)
+        .split("\u2502")
+        .map((column) => sanitizeDisplayString(column)),
+    )
+    .filter((columns) => columns.some(Boolean));
+}
+
+async function persistLocalConfig({ agentosUrl, configDir, dashboardUrl, hermesUrl, mode, pairingCode }) {
+  const targetDir = configDir ?? join(homedir(), ".agentos", "hermes");
+  const targetPath = join(targetDir, "connection.json");
+  const body = {
+    agentosUrl,
+    createdAt: new Date().toISOString(),
+    dashboardUrl,
+    hermesUrl,
+    mode,
+    pairingCode,
+  };
+
+  await mkdir(targetDir, { recursive: true });
+  await writeFile(targetPath, `${JSON.stringify(body, null, 2)}\n`, { mode: 0o600 });
+
+  return targetPath;
+}
+
+async function postHeartbeat(agentosUrl, pairingCode, payload) {
+  const response = await fetch(
+    `${agentosUrl}/api/hermes/pairing-sessions/${encodeURIComponent(pairingCode)}/heartbeat`,
+    {
+      body: JSON.stringify(payload),
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json",
+      },
+      method: "POST",
+    },
+  );
+  const text = await response.text();
+  const body = text ? JSON.parse(text) : {};
+
+  if (!response.ok) {
+    const message = typeof body.error === "string" ? body.error : `AgentOS returned ${response.status}.`;
+    throw new Error(message);
+  }
+
+  return body;
+}
+
+async function runHeartbeatLoop(sendHeartbeat, intervalMs) {
+  if (!Number.isFinite(intervalMs) || intervalMs < 1000) {
+    throw new Error("--interval-ms must be at least 1000.");
+  }
+
+  let stopping = false;
+  let interval;
+
+  await new Promise((resolve, reject) => {
+    const stop = () => {
+      stopping = true;
+      clearInterval(interval);
+      resolve();
+    };
+
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+
+    interval = setInterval(() => {
+      void sendHeartbeat()
+        .then((session) => {
+          if (!stopping) {
+            console.log(`Heartbeat accepted at ${session.lastHeartbeatAt ?? new Date().toISOString()}`);
+          }
+        })
+        .catch((error) => {
+          clearInterval(interval);
+          reject(error);
+        });
+    }, intervalMs);
+  });
+}
+
+function normalizeBaseUrl(value) {
+  return value.replace(/\/$/, "");
+}
+
+function stripAnsi(value) {
+  return value.replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "");
+}
+
+function sanitizeDisplayString(value, maxLength = 220) {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const compacted = value.replace(/\s+/g, " ").trim();
+
+  if (!compacted || compacted === "\u2014") {
+    return undefined;
+  }
+
+  return compacted.slice(0, maxLength);
+}
+
+function parseNumber(value) {
+  if (!value) {
+    return undefined;
+  }
+
+  const parsed = Number(String(value).replaceAll(",", ""));
+
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function formatCompactNumber(value) {
+  if (!Number.isFinite(value)) {
+    return "0";
+  }
+
+  if (value >= 1_000_000) {
+    return `${(value / 1_000_000).toFixed(value >= 10_000_000 ? 1 : 2)}M`;
+  }
+
+  if (value >= 1_000) {
+    return `${(value / 1_000).toFixed(value >= 10_000 ? 1 : 2)}K`;
+  }
+
+  return String(value);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function sanitizeDeliveryTarget(value) {
+  const safeValue = sanitizeDisplayString(value);
+
+  if (!safeValue) {
+    return undefined;
+  }
+
+  if (safeValue.includes(":")) {
+    return safeValue.split(":")[0];
+  }
+
+  return safeValue;
+}
+
+function redactLocalPath(value) {
+  if (!value) {
+    return undefined;
+  }
+
+  return value.replaceAll(homedir(), "~");
+}
+
+function redactSensitiveContent(value) {
+  if (!value) {
+    return "";
+  }
+
+  return value
+    .replaceAll(homedir(), "~")
+    .replace(
+      /^(\s*[\w.-]*(?:api[_-]?key|token|secret|password|credential|private[_-]?key|auth|cookie|session)[\w.-]*\s*[:=]\s*).+$/gim,
+      "$1[redacted]",
+    )
+    .replace(/\bsk-[A-Za-z0-9_-]{16,}\b/g, "[redacted-openai-key]")
+    .replace(/\bgh[pousr]_[A-Za-z0-9_]{16,}\b/g, "[redacted-github-token]")
+    .replace(/\bxox[baprs]-[A-Za-z0-9-]{16,}\b/g, "[redacted-slack-token]")
+    .replace(/\bAKIA[0-9A-Z]{16}\b/g, "[redacted-aws-key]")
+    .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "[redacted-private-key]");
+}
+
+function compactObject(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => {
+      if (entry === undefined || entry === null) {
+        return false;
+      }
+
+      if (Array.isArray(entry)) {
+        return entry.length > 0;
+      }
+
+      return true;
+    }),
+  );
+}
+
+function printHelp() {
+  console.log(`AgentOS Hermes connector ${VERSION}
+
+Usage:
+  agentos-hermes connect --pair <code> [options]
+
+Commands:
+  connect    Pair the local Hermes agent with AgentOS
+`);
+}
+
+function printConnectHelp() {
+  console.log(`Usage:
+  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
+  --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
+  --once               Send one heartbeat and exit, useful for CI and smoke tests
+`);
+}
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@agentworkspaceos/hermes",
+  "version": "0.1.0",
+  "description": "AgentOS connector CLI for pairing a local Hermes runtime with an AgentOS workspace.",
+  "type": "module",
+  "bin": {
+    "agentos-hermes": "bin/agentos-hermes.js"
+  },
+  "files": [
+    "bin/agentos-hermes.js",
+    "README.md"
+  ],
+  "scripts": {
+    "cli": "node bin/agentos-hermes.js",
+    "test": "node --test tests/**/*.test.js",
+    "pack:dry-run": "npm pack --dry-run",
+    "publish:public": "npm publish --access public"
+  },
+  "keywords": [
+    "agentos",
+    "hermes",
+    "connector",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}