@cotal-ai/connector-hermes 0.1.0 → 0.3.0

package/bin/install.mjs

@@ -2,44 +2,143 @@
 /**
  * `npx @cotal-ai/connector-hermes install`
  *
- * Installs the Cotal plugin into an existing Hermes so the gateway can join a Cotal mesh.
- * Copies this package's `plugin/cotal` (including the bundled `_sidecar/standalone.cjs`) into
- * `<HERMES_HOME>/plugins/cotal` and enables it.
+ * Guided install of the Cotal plugin into an existing Hermes so its gateway can join a Cotal mesh.
+ * Copies this package's `plugin/cotal` (incl. the bundled `_sidecar/standalone.cjs`) into
+ * `<HERMES_HOME>/plugins/cotal`, enables it, optionally writes your mesh config to
+ * `<HERMES_HOME>/.env`, and checks the mesh is reachable.
  *
- * House rule: no fallbacks. If Hermes isn't installed we fail loudly and write NOTHING — no
- * orphaned `~/.hermes/plugins/`. We resolve the Hermes home honestly (HERMES_HOME first), never
- * assuming a fixed path.
+ * Interactive when run in a TTY; non-interactive with `--yes` (or no TTY), taking config from
+ * `--link/--space/--name/--server` flags or the matching `COTAL_*` env vars.
+ *
+ * House rule: no fallbacks. If Hermes isn't installed we fail loudly and write NOTHING.
  */
 import { execFileSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createConnection } from "node:net";
 import { homedir } from "node:os";
 import { join, sep } from "node:path";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
 const PKG_ROOT = fileURLToPath(new URL("..", import.meta.url));
 const PLUGIN_SRC = join(PKG_ROOT, "plugin", "cotal");
 const SIDECAR = join(PLUGIN_SRC, "_sidecar", "standalone.cjs");
 
-function die(msg) {
+const DEFAULTS = { space: "demo", name: "my-hermes", server: "nats://127.0.0.1:4222" };
+
+const die = (msg) => {
   process.stderr.write(`✗ ${msg}\n`);
   process.exit(1);
+};
+const info = (msg) => process.stdout.write(`${msg}\n`);
+
+function usage() {
+  info("usage: npx @cotal-ai/connector-hermes install [--yes] [--link <url> | --space <s> --name <n> --server <url>]");
 }
-function info(msg) {
-  process.stdout.write(`${msg}\n`);
+
+// ---- arg parsing ------------------------------------------------------------
+function parseFlags(argv) {
+  const f = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--yes" || a === "-y") f.yes = true;
+    else if (a.startsWith("--")) {
+      const [k, inline] = a.slice(2).split("=");
+      f[k] = inline ?? (argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : true);
+    }
+  }
+  return f;
 }
 
-function usage() {
-  info("usage: npx @cotal-ai/connector-hermes install");
-  info("  Installs the Cotal plugin into your Hermes (HERMES_HOME or ~/.hermes).");
+// ---- mesh config gathering --------------------------------------------------
+async function promptConfig() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    info("\nCotal mesh — paste a join link (cotal://token@host/space), or press Enter to set it manually:");
+    const link = (await rl.question("  link: ")).trim();
+    if (link) {
+      const name = (await rl.question(`  name [${DEFAULTS.name}]: `)).trim() || DEFAULTS.name;
+      return { COTAL_LINK: link, COTAL_NAME: name };
+    }
+    const space = (await rl.question(`  space  [${DEFAULTS.space}]: `)).trim() || DEFAULTS.space;
+    const name = (await rl.question(`  name   [${DEFAULTS.name}]: `)).trim() || DEFAULTS.name;
+    const server = (await rl.question(`  server [${DEFAULTS.server}]: `)).trim() || DEFAULTS.server;
+    return { COTAL_SPACE: space, COTAL_NAME: name, COTAL_SERVERS: server };
+  } finally {
+    rl.close();
+  }
+}
+
+function configFromFlags(flags) {
+  const link = flags.link || process.env.COTAL_LINK;
+  if (link) return { COTAL_LINK: link, COTAL_NAME: flags.name || process.env.COTAL_NAME || DEFAULTS.name };
+  const space = flags.space || process.env.COTAL_SPACE;
+  const server = flags.server || process.env.COTAL_SERVERS;
+  if (!space && !server) return {}; // nothing supplied → skip .env, print manual next steps
+  return {
+    COTAL_SPACE: space || DEFAULTS.space,
+    COTAL_NAME: flags.name || process.env.COTAL_NAME || DEFAULTS.name,
+    COTAL_SERVERS: server || DEFAULTS.server,
+  };
+}
+
+// ---- ~/.hermes/.env editing (idempotent) ------------------------------------
+function writeEnv(file, set) {
+  // Link mode and manual mode are mutually exclusive; comment out the other mode's keys so a
+  // re-run never leaves a stale COTAL_SPACE overriding a new COTAL_LINK (individual vars win in
+  // configFromEnv).
+  const drop = set.COTAL_LINK ? ["COTAL_SPACE", "COTAL_SERVERS"] : ["COTAL_LINK"];
+  const lines = existsSync(file) ? readFileSync(file, "utf8").split("\n") : [];
+  const keyOf = (l) => l.replace(/^#\s*/, "").split("=")[0].trim();
+  for (const [k, v] of Object.entries(set)) {
+    const line = `${k}=${v}`;
+    const i = lines.findIndex((l) => keyOf(l) === k);
+    if (i >= 0) lines[i] = line;
+    else lines.push(line);
+  }
+  for (let i = 0; i < lines.length; i++) {
+    if (drop.includes(keyOf(lines[i])) && !lines[i].trimStart().startsWith("#")) lines[i] = `# ${lines[i]}`;
+  }
+  writeFileSync(file, lines.join("\n").replace(/\n*$/, "\n"));
+}
+
+// ---- mesh reachability ------------------------------------------------------
+function hostPort(server) {
+  try {
+    const u = new URL(server.replace(/^(cotals?|nats):\/\//, "http://"));
+    return { host: u.hostname, port: Number(u.port || 4222) };
+  } catch {
+    return undefined;
+  }
+}
+function reachable(server) {
+  const hp = hostPort(server);
+  if (!hp) return Promise.resolve(false);
+  return new Promise((res) => {
+    const s = createConnection({ host: hp.host, port: hp.port });
+    const done = (ok) => {
+      try {
+        s.destroy();
+      } catch {
+        /* ignore */
+      }
+      res(ok);
+    };
+    s.setTimeout(2000);
+    s.once("connect", () => done(true));
+    s.once("timeout", () => done(false));
+    s.once("error", () => done(false));
+  });
 }
 
-const cmd = process.argv[2];
-if (cmd !== "install") {
+// ---- main -------------------------------------------------------------------
+const args = process.argv.slice(2);
+if (args[0] !== "install") {
   usage();
-  process.exit(cmd ? 1 : 0);
+  process.exit(args[0] ? 1 : 0);
 }
+const flags = parseFlags(args.slice(1));
 
-// 1. Require a working Hermes — refuse (writing nothing) if absent.
 function hermesVersion() {
   try {
     return execFileSync("hermes", ["--version"], { encoding: "utf8" }).trim();
@@ -47,6 +146,7 @@ function hermesVersion() {
     return undefined;
   }
 }
+
 const version = hermesVersion();
 if (!version) {
   die(
@@ -55,45 +155,56 @@ if (!version) {
       "  then re-run: npx @cotal-ai/connector-hermes install",
   );
 }
-
-// 2. The bundled sidecar must be present (it ships in the npm package; a raw source checkout
-//    needs `pnpm --filter @cotal-ai/connector-hermes build` first). No silent half-install.
 if (!existsSync(SIDECAR)) {
   die(
     `bundled sidecar missing at ${SIDECAR}\n` +
       "  (running from source? build it first: pnpm --filter @cotal-ai/connector-hermes build)",
   );
 }
+info(`✓ Hermes detected — ${version.split("·")[0].trim()}`);
 
-// 3. Resolve the Hermes home honestly: HERMES_HOME wins, else ~/.hermes.
 const hermesHome = process.env.HERMES_HOME?.trim() || join(homedir(), ".hermes");
+const interactive = Boolean(process.stdin.isTTY) && !flags.yes;
+const meshEnv = interactive ? await promptConfig() : configFromFlags(flags);
+
+// Write mesh config to <home>/.env (if any was gathered).
+if (Object.keys(meshEnv).length) {
+  const envFile = join(hermesHome, ".env");
+  mkdirSync(hermesHome, { recursive: true });
+  writeEnv(envFile, meshEnv);
+  info(`✓ Wrote ${Object.keys(meshEnv).join(", ")} to ${envFile}`);
+
+  // Best-effort reachability check.
+  const server = meshEnv.COTAL_SERVERS || meshEnv.COTAL_LINK;
+  if (server) {
+    const ok = await reachable(server);
+    info(ok ? `✓ Mesh reachable` : `✗ Mesh not reachable at ${hostPort(server)?.host}:${hostPort(server)?.port} — start it (e.g. \`nats-server -js\`) before \`hermes gateway run\``);
+  }
+}
+
+// Copy the plugin + enable it.
 const pluginsDir = join(hermesHome, "plugins");
 const dest = join(pluginsDir, "cotal");
-
-info(`Hermes: ${version}`);
-info(`Installing the Cotal plugin into ${dest} ...`);
 mkdirSync(pluginsDir, { recursive: true });
-rmSync(dest, { recursive: true, force: true }); // clean reinstall (overwrite stale code)
+rmSync(dest, { recursive: true, force: true });
 cpSync(PLUGIN_SRC, dest, {
   recursive: true,
   filter: (src) => !src.includes(`${sep}__pycache__`) && !src.endsWith(".pyc"),
 });
-
-// 4. Enable it via Hermes' own command (it's discovered now that it's in plugins/).
 try {
   execFileSync("hermes", ["plugins", "enable", "cotal"], { stdio: "inherit" });
 } catch {
   die(
     "copied the plugin but `hermes plugins enable cotal` failed.\n" +
-      "  Enable it manually: `hermes plugins enable cotal` (or add `cotal` to plugins.enabled in config.yaml).",
+      "  Enable it manually: `hermes plugins enable cotal`.",
   );
 }
 
 info("\n✓ Cotal plugin installed + enabled.\n");
-info("Next: point it at a mesh, then run the gateway:");
-info("  # add to ~/.hermes/.env  (or the matching HERMES_HOME)");
-info("  COTAL_SPACE=demo");
-info("  COTAL_NAME=my-hermes");
-info("  COTAL_SERVERS=nats://127.0.0.1:4222");
-info("");
-info("  hermes gateway run");
+if (Object.keys(meshEnv).length) {
+  info("Run it on the mesh:");
+  info("  hermes gateway run");
+} else {
+  info("Next: set your mesh in ~/.hermes/.env (COTAL_LINK, or COTAL_SPACE/COTAL_NAME/COTAL_SERVERS),");
+  info("  then: hermes gateway run");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cotal-ai/connector-hermes",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -22,14 +22,14 @@
   "dependencies": {
     "tsx": "^4.22.4",
     "zod": "^4.4.3",
-    "@cotal-ai/connector-core": "0.2.0"
+    "@cotal-ai/connector-core": "0.3.0"
   },
   "peerDependencies": {
-    "@cotal-ai/core": "0.1.3"
+    "@cotal-ai/core": ">=0.1.0"
   },
   "devDependencies": {
     "esbuild": "^0.28.0",
-    "@cotal-ai/core": "0.1.3"
+    "@cotal-ai/core": "0.3.0"
   },
   "files": [
     "bin",

package/plugin/cotal/_sidecar/standalone.cjs

@@ -17919,6 +17919,15 @@ var MeshAgent = class extends import_node_events2.EventEmitter {
       args: { name, graceful: opts?.graceful ?? true }
     });
   }
+  /** Ask the manager to purge the space's retained chat backlog (its `purge` op). Cleanup only —
+   *  it doesn't touch live agents or the anycast work queue. `includeDms` also clears DM history. */
+  async purgeHistory(opts) {
+    this.assertConnected();
+    return this.ep.requestControl("manager", {
+      op: "purge",
+      args: { includeDms: opts?.includeDms ?? false }
+    });
+  }
   /** Define a persona and persist it as config (the manager's `definePersona` op writes
    *  .cotal/agents/<name>.md). On success, announce it on the channel — the "send it out"
    *  half — so peers see the new persona; `spawn(name)` then launches an agent wearing it. */
@@ -32870,6 +32879,27 @@ ${info}${caught}`);
         }
       }
     },
+    {
+      name: "cotal_purge",
+      title: "Cotal: clear chat history",
+      description: "Ask the manager to purge this space's retained chat backlog (channel history). Set includeDms to also clear direct-message history. Cleanup only \u2014 it does not affect live agents or the anycast work queue. Irreversible.",
+      schema: {
+        includeDms: external_exports.boolean().optional().describe("Default false: channel history only. true = also purge DM history.")
+      },
+      async run(agent, _config, { includeDms }) {
+        try {
+          const reply = await agent.purgeHistory({ includeDms });
+          if (!reply.ok)
+            return err(`Couldn't purge history: ${reply.error ?? "manager refused"}`);
+          const d = reply.data;
+          const chat = d?.chat ?? 0;
+          const dm = d?.dm;
+          return ok(`Cleared ${chat} channel message${chat === 1 ? "" : "s"}${dm === void 0 ? "" : ` and ${dm} DM${dm === 1 ? "" : "s"}`} from "${_config.space}".`);
+        } catch (e) {
+          return err(`Couldn't purge history: no manager reachable (${e.message}). Is the manager running?`);
+        }
+      }
+    },
     {
       name: "cotal_persona",
       title: "Cotal: define a persona",