@haven_ai/connect 0.1.21-alpha.0 → 0.1.22-alpha.0

package/README.md

@@ -25,3 +25,25 @@ Do not point it at a project repository, shared folder, or cloud-synced folder.
 Use `--ack-local-tools` with Haven-generated setup prompts. It prepares the
 local Haven tools acknowledgement during setup so Codex and Claude Code can load
 Haven after a normal restart.
+
+## Supported runtimes
+
+The default setup writes the hosted Haven MCP (using the agent API key for
+identity) plus a separate local signer. The API key identifies the agent; the
+locally held signer key and the user's approved Haven wallet rules remain the
+spending authority.
+
+| Runtime | Configuration written by setup | Reload behaviour |
+| --- | --- | --- |
+| Claude Code | User MCP registry | Start a new session |
+| Codex CLI / Codex Desktop | `~/.codex/config.toml` | Start a new session / restart the app |
+| Cursor | Cursor MCP configuration | Reloads automatically |
+| VS Code / VS Code Insiders | VS Code MCP configuration | Reloads automatically |
+| Claude Desktop | Claude Desktop MCP configuration | Restart the app |
+| Hermes Agent | `$HERMES_HOME/config.yaml` + `.env`, or `~/.hermes/config.yaml` + `.env` | Start a new session; gateway users run `/restart` |
+
+For Hermes, Connect stores the hosted-MCP API key in the matching owner-only
+`.env` file and keeps only `Bearer ${MCP_HAVEN_API_KEY}` in `config.yaml`.
+Hermes requires its Python MCP SDK support to be installed. If Haven tools do
+not appear after restart, run `pip install mcp` in the Hermes environment, then
+restart Hermes and check `hermes mcp list`.

package/dist/cli.cjs

@@ -8,6 +8,7 @@ var os = require('os');
 var path = require('path');
 var child_process = require('child_process');
 var util = require('util');
+var yaml = require('yaml');
 var mcp = require('@haven_ai/mcp');
 var sdk = require('@haven_ai/sdk');
 var signer = require('@haven_ai/signer');
@@ -236,9 +237,9 @@ var MCP_RUNTIME_MANIFEST = {
   mcpPackage: "@haven_ai/mcp",
   mcpVersion: mcp.MCP_VERSION,
   sdkPackage: "@haven_ai/sdk",
-  sdkVersion: "0.1.21-alpha.0",
+  sdkVersion: "0.1.22-alpha.0",
   signerPackage: "@haven_ai/signer",
-  signerVersion: "0.1.21-alpha.0",
+  signerVersion: "0.1.22-alpha.0",
   // Sourced from the SDK, never a literal (#1161). This field read '20.0.0'
   // while every package's `engines` said `>=24` and the docs said `>=24.0.0`,
   // so the guard that was supposed to enforce the floor waved Node v23 through
@@ -260,13 +261,20 @@ function signerPackageSpec() {
 }
 
 // src/config-writers.ts
+var HERMES_API_KEY_ENV = "MCP_HAVEN_API_KEY";
+var HermesConfigRecoveryError = class extends Error {
+  constructor() {
+    super("Hermes configuration recovery did not complete");
+    this.name = "HermesConfigRecoveryError";
+  }
+};
 var InvalidCodexTomlError = class extends Error {
   constructor(message) {
     super(message);
     this.name = "InvalidCodexTomlError";
   }
 };
-async function writeRuntimeConfig(input) {
+async function writeRuntimeConfig(input, deps = {}) {
   switch (input.runtime) {
     case "codex-cli":
     case "codex-desktop":
@@ -279,6 +287,8 @@ async function writeRuntimeConfig(input) {
       return writeJsonRuntimeConfig(input, vscodeInsidersConfigPath(input.homeDir), "servers");
     case "claude-desktop":
       return writeJsonRuntimeConfig(input, claudeDesktopConfigPath(input.homeDir), "mcpServers");
+    case "hermes":
+      return writeHermesConfig(input, deps);
     default:
       return {
         hostedConfigured: false,
@@ -332,6 +342,115 @@ function mergeJsonMcpConfig(existingJson, serverRoot, hostedServer, signerServer
   return `${JSON.stringify(config, null, 2)}
 `;
 }
+function mergeHermesYaml(existingYaml, hostedServer, signerServer) {
+  if (!existingYaml?.trim()) return renderHermesYaml({ haven: hostedServer, "haven-signer": signerServer });
+  const doc = yaml.parseDocument(existingYaml, { keepSourceTokens: true });
+  if (doc.errors.length > 0 || !yaml.isMap(doc.contents)) {
+    throw new Error("Hermes config must be a YAML object");
+  }
+  const mcpPair = doc.contents.items.find((item) => item.key?.toString() === "mcp_servers");
+  const existingServers = mcpPair && yaml.isMap(mcpPair.value) ? mcpPair.value.toJSON() : {};
+  const servers = isRecord(existingServers) ? existingServers : {};
+  const mergedServers = {
+    ...servers,
+    haven: hostedServer,
+    "haven-signer": signerServer
+  };
+  if (!mcpPair) {
+    return appendHermesMcpServers(existingYaml, mergedServers);
+  }
+  if (!mcpPair.value?.range) return replaceEmptyHermesMcpServers(existingYaml, mcpPair.key?.range, mergedServers);
+  return replaceHermesMcpServers(existingYaml, mcpPair.key?.range, mcpPair.value.range, mergedServers);
+}
+function mergeHermesEnv(existingEnv, apiKey) {
+  if (/[\r\n]/.test(apiKey)) throw new Error("Hermes API key must be a single line");
+  const assignment = `${HERMES_API_KEY_ENV}=${apiKey}`;
+  if (!existingEnv) return `${assignment}
+`;
+  const lineEnding = existingEnv.includes("\r\n") ? "\r\n" : "\n";
+  const hasTrailingNewline = /\r?\n$/.test(existingEnv);
+  const lines = existingEnv.split(/\r?\n/);
+  if (hasTrailingNewline) lines.pop();
+  let found = false;
+  const merged = lines.flatMap((line) => {
+    if (isHermesEnvAssignment(line)) {
+      if (found) return [];
+      found = true;
+      return [assignment];
+    }
+    if (isAmbiguousHermesEnvLine(line)) {
+      throw new Error("Hermes environment contains an ambiguous managed key");
+    }
+    return [line];
+  });
+  if (!found) {
+    return `${existingEnv}${hasTrailingNewline ? "" : lineEnding}${assignment}${lineEnding}`;
+  }
+  return `${merged.join(lineEnding)}${hasTrailingNewline ? lineEnding : ""}`;
+}
+function isHermesEnvAssignment(line) {
+  return /^\s*(?:export[ \t]+)?MCP_HAVEN_API_KEY[ \t]*=/.test(line);
+}
+function isAmbiguousHermesEnvLine(line) {
+  return /^\s*(?:export[ \t]+)?MCP_HAVEN_API_KEY\b/.test(line);
+}
+function appendHermesMcpServers(source, servers) {
+  const documentEnd = /(?:^|\n)[ \t]*\.\.\.[ \t]*(?:#[^\n]*)?\r?\n?$/.exec(source);
+  if (documentEnd) {
+    const markerStart = documentEnd.index + (documentEnd[0].startsWith("\n") ? 1 : 0);
+    const beforeMarker = source.slice(0, markerStart);
+    return `${beforeMarker}${beforeMarker.endsWith("\n") ? "" : "\n"}${renderHermesMcpServers(servers, "")}
+${source.slice(markerStart)}`;
+  }
+  const separator = source.endsWith("\n") ? "" : "\n";
+  return `${source}${separator}${renderHermesMcpServers(servers, "")}
+`;
+}
+function replaceHermesMcpServers(source, keyRange, valueRange, servers) {
+  const valueStart = valueRange[0];
+  const valueEnd = valueRange[1];
+  const valueLineStart = source.lastIndexOf("\n", valueStart - 1) + 1;
+  const keyStartsOnValueLine = keyRange?.[0] !== void 0 && keyRange[0] >= valueLineStart;
+  const nestedIndent = `${source.slice(valueLineStart, keyRange?.[0] ?? valueLineStart)}  `;
+  if (keyStartsOnValueLine) {
+    const keyStart = keyRange[0];
+    const keyEnd = keyRange[1];
+    const replacement2 = `${source.slice(keyStart, keyEnd)}:
+${renderHermesMcpServerEntries(servers, nestedIndent)}`;
+    const needsTrailingNewline2 = valueEnd < source.length && !source.slice(valueEnd).startsWith("\n");
+    return `${source.slice(0, keyStart)}${replacement2}${needsTrailingNewline2 ? "\n" : ""}${source.slice(valueEnd)}`;
+  }
+  const indent = source.slice(valueLineStart, valueStart);
+  const rendered = yaml.stringify(servers, { lineWidth: 120 }).trimEnd();
+  const replacement = rendered.split("\n").map((line, index) => index === 0 ? line : `${indent}${line}`).join("\n");
+  const needsTrailingNewline = valueEnd < source.length && !source.slice(valueEnd).startsWith("\n");
+  return `${source.slice(0, valueStart)}${replacement}${needsTrailingNewline ? "\n" : ""}${source.slice(valueEnd)}`;
+}
+function replaceEmptyHermesMcpServers(source, keyRange, servers) {
+  if (!keyRange) throw new Error("Hermes config mcp_servers key is invalid");
+  const keyStart = keyRange[0];
+  const keyEnd = keyRange[1];
+  const lineStart = source.lastIndexOf("\n", keyStart - 1) + 1;
+  const lineEnd = source.indexOf("\n", keyEnd);
+  const nestedIndent = `${source.slice(lineStart, keyStart)}  `;
+  const replacement = `${source.slice(keyStart, keyEnd)}:
+${renderHermesMcpServerEntries(servers, nestedIndent)}`;
+  return `${source.slice(0, keyStart)}${replacement}${lineEnd === -1 ? "\n" : source.slice(lineEnd)}`;
+}
+function renderHermesYaml(servers) {
+  return `${renderHermesMcpServers(servers, "")}
+`;
+}
+function renderHermesMcpServers(servers, indent) {
+  return `mcp_servers:
+${renderHermesMcpServerEntries(servers, `${indent}  `)}`;
+}
+function renderHermesMcpServerEntries(servers, indent) {
+  return yaml.stringify(servers, { lineWidth: 120 }).trimEnd().split("\n").map((line) => `${indent}${line}`).join("\n");
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
 function mergeCodexToml(existingToml, localMcpCommand) {
   let next = removeTomlTableTree(removeTomlTableTree(existingToml, "mcp_servers.haven"), "mcp_servers.haven_signer");
   next = next.trimEnd();
@@ -402,6 +521,82 @@ async function writeJsonRuntimeConfig(input, target, serverRoot) {
     };
   }
 }
+async function writeHermesConfig(input, deps) {
+  const target = hermesConfigPath(input.homeDir);
+  const envTarget = hermesEnvPath(input.homeDir);
+  try {
+    const [existing, existingEnv] = await Promise.all([readOptional(target), readOptional(envTarget)]);
+    const hostedServer = {
+      ...buildHostedServer(input.hostedMcpUrl, `\${${HERMES_API_KEY_ENV}}`, input.runtime),
+      enabled: true
+    };
+    const signerServer = {
+      ...buildSignerServer(resolveSignerLaunchSpec(input), input.runtime),
+      enabled: true
+    };
+    const merged = mergeHermesYaml(
+      existing,
+      hostedServer,
+      signerServer
+    );
+    const mergedEnv = mergeHermesEnv(existingEnv, input.apiKey);
+    const writeText = deps.writeOwnerOnlyText ?? writeOwnerOnlyText;
+    await writeText(envTarget, mergedEnv);
+    try {
+      await writeText(target, merged);
+    } catch (err) {
+      const recovered = await restoreHermesFiles(target, existing, envTarget, existingEnv, writeText);
+      if (!recovered) throw new HermesConfigRecoveryError();
+      throw err;
+    }
+    return {
+      hostedConfigured: true,
+      signerConfigured: true,
+      localMcpConfigured: false,
+      runtimeMcpMode: "hosted_plus_signer",
+      target: "Hermes Agent config",
+      changed: existing !== merged || existingEnv !== mergedEnv,
+      restartRequired: true,
+      messages: [
+        `Updated Haven MCP entries in ${target}; stored the hosted MCP identity in ${envTarget}.`,
+        "Restart Hermes (start a new session; gateway users: /restart), then verify with `hermes mcp list`, `hermes mcp test haven`, and `hermes mcp test haven-signer`.",
+        "If no mcp_* tools appear after restart, ensure the MCP SDK is installed in Hermes: pip install mcp"
+      ]
+    };
+  } catch (err) {
+    const recoveryIncomplete = err instanceof HermesConfigRecoveryError;
+    return {
+      hostedConfigured: false,
+      signerConfigured: false,
+      localMcpConfigured: false,
+      runtimeMcpMode: "hosted_plus_signer",
+      target: "Hermes Agent config",
+      changed: false,
+      restartRequired: true,
+      messages: [recoveryIncomplete ? "Could not update Hermes Agent config. Recovery did not complete; inspect the Hermes configuration before retrying." : "Could not update Hermes Agent config. Existing configuration was left unchanged."],
+      errorCode: "runtime_config_write_failed"
+    };
+  }
+}
+async function restoreHermesFiles(configPath, existingConfig, envPath, existingEnv, writeText) {
+  const [envResult, configResult] = await Promise.allSettled([
+    restoreOptionalText(envPath, existingEnv, writeText),
+    restoreOptionalText(configPath, existingConfig, writeText)
+  ]);
+  return envResult.status === "fulfilled" && configResult.status === "fulfilled";
+}
+async function restoreOptionalText(path, existing, writeText) {
+  if (existing !== null) {
+    await writeText(path, existing);
+    return;
+  }
+  try {
+    await promises.unlink(path);
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") return;
+    throw err;
+  }
+}
 async function writeCodexConfig(input) {
   const target = codexConfigPath(input.homeDir);
   const local = input.mode === "local";
@@ -692,6 +887,15 @@ function claudeDesktopConfigPath(homeDir = os.homedir()) {
   }
   return path.resolve(homeDir, ".config", "Claude", "claude_desktop_config.json");
 }
+function hermesConfigPath(homeDir) {
+  return path.join(hermesHomePath(homeDir), "config.yaml");
+}
+function hermesEnvPath(homeDir) {
+  return path.join(hermesHomePath(homeDir), ".env");
+}
+function hermesHomePath(homeDir) {
+  return process.env.HERMES_HOME ?? path.join(homeDir ?? os.homedir(), ".hermes");
+}
 function configTargetLabel(runtime) {
   switch (runtime) {
     case "codex-cli":
@@ -1235,6 +1439,12 @@ var RUNTIME_PROFILES = {
     restartMode: "restart-app",
     canWriteRuntimeConfig: true
   },
+  hermes: {
+    id: "hermes",
+    label: "Hermes Agent",
+    restartMode: "restart-session",
+    canWriteRuntimeConfig: true
+  },
   other: {
     id: "other",
     label: "Other agent runtime",
@@ -1272,6 +1482,10 @@ var RUNTIME_ALIASES = {
   "claude_desktop": "claude-desktop",
   claudesktop: "claude-desktop",
   desktop: "claude-desktop",
+  hermes: "hermes",
+  "hermes-agent": "hermes",
+  hermes_agent: "hermes",
+  hermesagent: "hermes",
   other: "other",
   manual: "other"
 };
@@ -1299,6 +1513,7 @@ function detectRuntime(env) {
   if (env.CLAUDECODE || env.CLAUDE_CODE || env.CLAUDECODE_CWD) return "claude-code";
   if (env.CODEX_SANDBOX || env.CODEX_HOME || env.CODEX_CWD) return "codex-cli";
   if (env.VSCODE_CWD || env.VSCODE_IPC_HOOK_CLI || env.TERM_PROGRAM === "vscode") return "vscode";
+  if (env.HERMES_HOME || env.HERMES_AGENT) return "hermes";
   return null;
 }
 async function acknowledgeLocalSignerConsent(signerPath, log) {
@@ -1708,7 +1923,7 @@ function localRuntimePrepareErrorCode(err) {
 }
 
 // src/runtime.ts
-var CONNECTOR_VERSION = "0.1.21-alpha.0";
+var CONNECTOR_VERSION = "0.1.22-alpha.0";
 async function runConnect(options, deps = {}) {
   assertSupportedNodeVersion(deps.nodeVersion, MCP_RUNTIME_MANIFEST.minimumNodeVersion);
   const connectorVersion = options.connectorVersion ?? CONNECTOR_VERSION;
@@ -1941,7 +2156,7 @@ function helpText() {
     "Options:",
     "  --setup <token>            Short-lived setup token from Haven.",
     "  --api <url>                Haven backend API URL. Defaults to HAVEN_API_URL or http://localhost:3001.",
-    "  --runtime <name>           Agent runtime hint, such as claude-code, codex-cli, codex-desktop, cursor, vscode, or claude-desktop.",
+    "  --runtime <name>           Agent runtime hint, such as claude-code, codex-cli, codex-desktop, cursor, vscode, claude-desktop, or hermes.",
     "  --credentials-dir <path>   Credential directory fallback. Defaults to ~/.haven/agents.",
     "  --environment-label <text> Non-sensitive label shown in Haven setup review.",
     "  --ack-local-tools          Write the one-time local Haven tools acknowledgement during setup.",