@hermespilot/link 0.4.6 → 0.4.8

package/README.md

@@ -15,6 +15,14 @@ npm install -g @hermespilot/link
 
 The package installs the `hermeslink` command. It does not start the service automatically during installation.
 
+If your shell cannot find `hermeslink` right after install, your npm global bin directory is probably not on `PATH`. On Unix-like systems you can run:
+
+```bash
+export PATH="$(npm prefix -g)/bin:$PATH"
+```
+
+You can also invoke the installed binary directly with `$(npm prefix -g)/bin/hermeslink`.
+
 ## Common commands
 
 ```bash

package/dist/{chunk-DUQDO2LQ.js → chunk-B42L327D.js}

@@ -4117,7 +4117,8 @@ function isConversationMissingError(error) {
 
 // src/hermes/gateway.ts
 import { execFile as execFile2, spawn } from "child_process";
-import { access, readFile as readFile5, stat as stat4 } from "fs/promises";
+import { constants as fsConstants } from "fs";
+import { access, readFile as readFile5, realpath, stat as stat4 } from "fs/promises";
 import path7 from "path";
 import { setTimeout as delay } from "timers/promises";
 import { promisify as promisify2 } from "util";
@@ -4132,7 +4133,7 @@ import os2 from "os";
 import path5 from "path";
 
 // src/constants.ts
-var LINK_VERSION = "0.4.6";
+var LINK_VERSION = "0.4.8";
 var LINK_COMMAND = "hermeslink";
 var LINK_DEFAULT_PORT = 52379;
 var LINK_RUNTIME_DIR_NAME = ".hermeslink";
@@ -4631,6 +4632,8 @@ var PROFILE_NAME_PATTERN = /^[a-zA-Z0-9._-]{1,64}$/u;
 var DASHBOARD_STATUS_URL = "http://127.0.0.1:9119/api/status";
 var DASHBOARD_STATUS_TIMEOUT_MS = 1500;
 var DEFAULT_VERSION_CACHE_TTL_MS = 6e4;
+var VERSION_METADATA_TIMEOUT_MS = 3e3;
+var VERSION_COMMAND_TIMEOUT_MS = 5e3;
 var MAX_VERSION_LOG_OUTPUT_LENGTH = 1200;
 var HERMES_GATEWAY_ENV_BLOCKLIST_PREFIXES = ["API_SERVER_"];
 var gatewayStartInFlightByProfile = /* @__PURE__ */ new Map();
@@ -4826,9 +4829,26 @@ async function readHermesVersion(options = {}) {
 }
 async function execHermesVersion(hermesBin, logger) {
   const failures = [];
+  try {
+    const metadataVersion = await readHermesPythonMetadataVersion(
+      hermesBin,
+      VERSION_METADATA_TIMEOUT_MS
+    );
+    if (metadataVersion) {
+      return metadataVersion;
+    }
+  } catch (error) {
+    const failure = describeVersionMetadataFailure(hermesBin, error);
+    failures.push(failure);
+    void logger?.debug("hermes_version_metadata_probe_failed", failure.fields);
+  }
   for (const args of [["--version"], ["version"]]) {
     try {
-      return await spawnHermesVersionCommand(hermesBin, args, 5e3);
+      return await spawnHermesVersionCommand(
+        hermesBin,
+        args,
+        VERSION_COMMAND_TIMEOUT_MS
+      );
     } catch (error) {
       const failure = describeVersionCommandFailure(hermesBin, args, error);
       failures.push(failure);
@@ -4844,6 +4864,109 @@ async function execHermesVersion(hermesBin, logger) {
   });
   throw new Error(summary);
 }
+async function readHermesPythonMetadataVersion(hermesBin, timeoutMs) {
+  const hermesPath = await resolveExecutablePath(hermesBin);
+  if (!hermesPath) {
+    return null;
+  }
+  const firstLine = await readFirstLine(hermesPath);
+  const interpreter = parsePythonShebang(firstLine);
+  if (!interpreter) {
+    return null;
+  }
+  return await spawnHermesMetadataCommand(interpreter, timeoutMs);
+}
+async function spawnHermesMetadataCommand(interpreter, timeoutMs) {
+  const script = [
+    "import importlib.metadata as metadata",
+    "try:",
+    '    version = metadata.version("hermes-agent")',
+    '    release_date = ""',
+    "except Exception:",
+    "    import hermes_cli",
+    '    version = getattr(hermes_cli, "__version__", "")',
+    '    release_date = getattr(hermes_cli, "__release_date__", "")',
+    "if not version:",
+    '    raise SystemExit("Hermes Agent version metadata not found")',
+    'suffix = f" ({release_date})" if release_date else ""',
+    'print(f"Hermes Agent v{version}{suffix}")',
+    ""
+  ].join("\n");
+  return await new Promise((resolve, reject) => {
+    const child = spawn(
+      interpreter.command,
+      [...interpreter.args, "-c", script],
+      {
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        env: { ...process.env, HERMES_NONINTERACTIVE: "1" }
+      }
+    );
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const timer = setTimeout(() => {
+      finish(() => {
+        reject(
+          createVersionCommandError(
+            `Hermes Python metadata probe timed out after ${timeoutMs}ms`,
+            { stdout, stderr, killed: true }
+          )
+        );
+      }, true);
+    }, timeoutMs);
+    const finish = (callback, kill = false) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      if (kill && child.pid && !child.killed) {
+        child.kill();
+      }
+      callback();
+    };
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.once("error", (error) => {
+      finish(() => {
+        reject(
+          createVersionCommandError(error.message, {
+            stdout,
+            stderr,
+            cause: error
+          })
+        );
+      });
+    });
+    child.once("close", (code, signal) => {
+      finish(() => {
+        const raw = `${stdout}
+${stderr}`.trim();
+        if (code === 0 && parseHermesVersion(raw)) {
+          resolve({ stdout: raw });
+          return;
+        }
+        reject(
+          createVersionCommandError(
+            `Hermes Python metadata probe exited with code ${code ?? "null"}`,
+            {
+              stdout,
+              stderr,
+              code,
+              signal,
+              killed: child.killed
+            }
+          )
+        );
+      });
+    });
+  });
+}
 async function spawnHermesVersionCommand(hermesBin, args, timeoutMs) {
   return await new Promise((resolve, reject) => {
     const child = spawn(hermesBin, args, {
@@ -5424,6 +5547,20 @@ function createVersionCommandError(message, details) {
   }
   return error;
 }
+function describeVersionMetadataFailure(hermesBin, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const details = readExecErrorDetails(error, message);
+  return {
+    summary: `${hermesBin} Python metadata probe failed: ${message}`,
+    fields: {
+      hermes_bin: hermesBin,
+      command: "python-metadata",
+      cwd: process.cwd(),
+      error: message,
+      ...details
+    }
+  };
+}
 function describeVersionCommandFailure(hermesBin, args, error) {
   const message = error instanceof Error ? error.message : String(error);
   const details = readExecErrorDetails(error, message);
@@ -5473,6 +5610,91 @@ function readExecErrorDetails(error, message) {
 function truncateVersionLogOutput(value) {
   return value.length > MAX_VERSION_LOG_OUTPUT_LENGTH ? `${value.slice(0, MAX_VERSION_LOG_OUTPUT_LENGTH)}...` : value;
 }
+async function resolveExecutablePath(command) {
+  const candidates = executablePathCandidates(command);
+  for (const candidate of candidates) {
+    try {
+      await access(candidate, fsConstants.X_OK);
+      return await realpath(candidate).catch(() => candidate);
+    } catch {
+    }
+  }
+  return null;
+}
+function executablePathCandidates(command) {
+  const normalized = command.trim();
+  if (!normalized) {
+    return [];
+  }
+  if (/[\\/]/u.test(normalized)) {
+    return withWindowsExecutableExtensions(normalized);
+  }
+  const pathEntries = (process.env.PATH ?? "").split(path7.delimiter).filter(Boolean);
+  return pathEntries.flatMap(
+    (entry) => withWindowsExecutableExtensions(path7.join(entry, normalized))
+  );
+}
+function withWindowsExecutableExtensions(filePath) {
+  if (process.platform !== "win32" || path7.extname(filePath)) {
+    return [filePath];
+  }
+  const extensions = (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean);
+  return [filePath, ...extensions.map((extension) => `${filePath}${extension}`)];
+}
+async function readFirstLine(filePath) {
+  const raw = await readFile5(filePath, "utf8");
+  return raw.split(/\r?\n/u, 1)[0] ?? "";
+}
+function parsePythonShebang(line) {
+  if (!line.startsWith("#!")) {
+    return null;
+  }
+  const parts = splitShellWords(line.slice(2).trim());
+  if (parts.length === 0) {
+    return null;
+  }
+  const commandName = path7.basename(parts[0] ?? "").toLowerCase();
+  if (commandName === "env") {
+    const args = expandEnvShebangArgs(parts.slice(1));
+    const pythonIndex = args.findIndex((part) => isPythonCommandName(part));
+    if (pythonIndex < 0) {
+      return null;
+    }
+    return {
+      command: parts[0],
+      args
+    };
+  }
+  if (!isPythonCommandName(commandName)) {
+    return null;
+  }
+  return {
+    command: parts[0],
+    args: parts.slice(1)
+  };
+}
+function isPythonCommandName(command) {
+  return /^python(?:\d+(?:\.\d+)?)?$/iu.test(path7.basename(command));
+}
+function expandEnvShebangArgs(args) {
+  const expanded = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "-S" && args[index + 1]) {
+      expanded.push(...splitShellWords(args[index + 1]));
+      index += 1;
+      continue;
+    }
+    if (arg !== "-S") {
+      expanded.push(arg);
+    }
+  }
+  return expanded;
+}
+function splitShellWords(value) {
+  const matches = value.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/gu);
+  return [...matches].map((match) => match[1] ?? match[2] ?? match[3] ?? "");
+}
 function compareSemver(left, right) {
   const leftParts = left.split(".").map((part) => Number.parseInt(part, 10));
   const rightParts = right.split(".").map((part) => Number.parseInt(part, 10));
@@ -7871,12 +8093,12 @@ var ConversationMetadataCoordinator = class {
     return { ...next, last_event_seq: event.seq, updated_at: event.created_at };
   }
   scheduleGeneratedTitleRefresh(conversationId) {
-    for (const delay2 of GENERATED_TITLE_RETRY_DELAYS_MS) {
+    for (const delay3 of GENERATED_TITLE_RETRY_DELAYS_MS) {
       setTimeout(() => {
         void this.generateTitleFromFirstRound(conversationId).catch(
           () => void 0
         );
-      }, delay2);
+      }, delay3);
     }
   }
   async renameConversation(conversationId, title, input) {
@@ -12677,7 +12899,7 @@ async function resolveHermesPythonCommand() {
   if (explicit) {
     return { command: explicit, args: [] };
   }
-  const hermesBin = await resolveExecutablePath(resolveHermesBin());
+  const hermesBin = await resolveExecutablePath2(resolveHermesBin());
   if (hermesBin) {
     const shebang = await readShebang(hermesBin);
     const command = shebangToPythonCommand(shebang);
@@ -12690,7 +12912,7 @@ async function resolveHermesPythonCommand() {
     args: []
   };
 }
-async function resolveExecutablePath(command) {
+async function resolveExecutablePath2(command) {
   if (path17.isAbsolute(command)) {
     return await isExecutableFile(command) ? command : null;
   }
@@ -16342,11 +16564,15 @@ function createHttpErrorMiddleware(logger) {
 import { execFile as execFile4 } from "child_process";
 import { readdir as readdir9, readFile as readFile12, rename as rename3, stat as stat12 } from "fs/promises";
 import path18 from "path";
+import { setTimeout as delay2 } from "timers/promises";
 import { promisify as promisify4 } from "util";
 import YAML2 from "yaml";
 var DEFAULT_PROFILE = "default";
 var PROFILE_NAME_PATTERN4 = /^[a-zA-Z0-9._-]{1,64}$/;
 var PROFILE_DELETE_TIMEOUT_MS = 3e4;
+var PROFILE_GATEWAY_STOP_TIMEOUT_MS = 3e3;
+var PROFILE_DELETE_STABLE_ABSENCE_MS = 1200;
+var PROFILE_DELETE_VERIFY_INTERVAL_MS = 150;
 var execFileAsync4 = promisify4(execFile4);
 async function listHermesProfiles(paths = resolveRuntimePaths()) {
   const profiles = /* @__PURE__ */ new Map();
@@ -16427,8 +16653,8 @@ async function deleteHermesProfile(name, paths = resolveRuntimePaths()) {
       `Profile "${name}" does not exist`
     );
   }
-  await deleteHermesProfileWithCli(name);
-  if (await pathExists(profile.path)) {
+  await deleteHermesProfileWithCliAndVerify(name, profile.path);
+  if (!await waitForProfilePathToRemainAbsent(profile.path)) {
     throw new LinkHttpError(
       502,
       "hermes_profile_delete_incomplete",
@@ -16512,6 +16738,116 @@ async function deleteHermesProfileWithCli(name) {
     );
   }
 }
+async function deleteHermesProfileWithCliAndVerify(name, profilePath) {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    await stopHermesGatewayProcessesForProfile(name);
+    if (attempt > 0 && !await pathExists(profilePath)) {
+      return;
+    }
+    await deleteHermesProfileWithCli(name);
+    if (await waitForProfilePathToRemainAbsent(profilePath)) {
+      return;
+    }
+  }
+}
+async function stopHermesGatewayProcessesForProfile(name) {
+  const pids = await findHermesGatewayProcessIdsForProfile(name);
+  if (pids.length === 0) {
+    return;
+  }
+  for (const pid of pids) {
+    killProcess(pid, "SIGTERM");
+  }
+  const remainingAfterTerm = await waitForProcessesToExit(
+    pids,
+    PROFILE_GATEWAY_STOP_TIMEOUT_MS
+  );
+  if (remainingAfterTerm.length === 0) {
+    return;
+  }
+  for (const pid of remainingAfterTerm) {
+    killProcess(pid, "SIGKILL");
+  }
+  const remainingAfterKill = await waitForProcessesToExit(
+    remainingAfterTerm,
+    PROFILE_GATEWAY_STOP_TIMEOUT_MS
+  );
+  if (remainingAfterKill.length > 0) {
+    throw new LinkHttpError(
+      502,
+      "hermes_profile_gateway_stop_failed",
+      `Could not stop Hermes Gateway process(es) for Profile "${name}": ${remainingAfterKill.join(", ")}`
+    );
+  }
+}
+async function findHermesGatewayProcessIdsForProfile(name) {
+  if (process.platform === "win32") {
+    return [];
+  }
+  try {
+    const output = await execFileAsync4("ps", ["-axo", "pid=,command="], {
+      timeout: 3e3,
+      windowsHide: true
+    });
+    return parseHermesGatewayProcessIds(output.stdout.toString(), name);
+  } catch {
+    return [];
+  }
+}
+function parseHermesGatewayProcessIds(output, name) {
+  const pids = [];
+  for (const line of output.split(/\r?\n/)) {
+    const match = /^\s*(\d+)\s+(.+)$/.exec(line);
+    if (!match) {
+      continue;
+    }
+    const pid = Number(match[1]);
+    const command = match[2];
+    if (Number.isSafeInteger(pid) && pid !== process.pid && isHermesGatewayRunCommandForProfile(command, name)) {
+      pids.push(pid);
+    }
+  }
+  return pids;
+}
+function isHermesGatewayRunCommandForProfile(command, name) {
+  const escapedName = escapeRegExp2(name);
+  return new RegExp(
+    String.raw`(?:^|\s)-p\s+${escapedName}\s+gateway\s+run(?:\s|$)`
+  ).test(command);
+}
+function killProcess(pid, signal) {
+  try {
+    process.kill(pid, signal);
+  } catch {
+  }
+}
+async function waitForProcessesToExit(pids, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let remaining = pids.filter(isProcessRunning);
+  while (remaining.length > 0 && Date.now() < deadline) {
+    await delay2(100);
+    remaining = remaining.filter(isProcessRunning);
+  }
+  return remaining;
+}
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return isNodeError14(error, "EPERM");
+  }
+}
+async function waitForProfilePathToRemainAbsent(profilePath) {
+  const deadline = Date.now() + PROFILE_DELETE_STABLE_ABSENCE_MS;
+  while (Date.now() < deadline) {
+    if (await pathExists(profilePath)) {
+      return false;
+    }
+    await delay2(PROFILE_DELETE_VERIFY_INTERVAL_MS);
+  }
+  return !await pathExists(profilePath);
+}
 function formatExecError(error) {
   if (!(error instanceof Error)) {
     return String(error);
@@ -16539,6 +16875,9 @@ function readExecErrorOutput2(error) {
 function isNodeError14(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
+function escapeRegExp2(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 async function countSkills(root) {
   const entries = await readdir9(root, { withFileTypes: true }).catch(
     (error) => {
@@ -17715,7 +18054,7 @@ async function writeEnvValues(profileName, values) {
   const nextLines = lines.map((line) => {
     const trimmed = line.trim();
     for (const [key, value] of remaining) {
-      const keyPattern = new RegExp(`^(?:export\\s+)?${escapeRegExp2(key)}=`, "u");
+      const keyPattern = new RegExp(`^(?:export\\s+)?${escapeRegExp3(key)}=`, "u");
       if (keyPattern.test(trimmed)) {
         remaining.delete(key);
         return `${key}=${formatEnvValue2(value)}`;
@@ -17897,7 +18236,7 @@ function formatEnvValue2(value) {
   }
   return JSON.stringify(value);
 }
-function escapeRegExp2(value) {
+function escapeRegExp3(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
 function isNodeError15(error, code) {
@@ -19226,7 +19565,7 @@ async function patchHermesMemoryEnv(profileName, patch) {
         `\u4E0D\u5141\u8BB8\u4ECE App \u5199\u5165 ${key}\u3002`
       );
     }
-    const keyPattern = new RegExp(`^(?:export\\s+)?${escapeRegExp3(key)}=`, "u");
+    const keyPattern = new RegExp(`^(?:export\\s+)?${escapeRegExp4(key)}=`, "u");
     let replaced = false;
     for (let index = 0; index < nextLines.length; index += 1) {
       if (keyPattern.test(nextLines[index].trim())) {
@@ -19447,7 +19786,7 @@ function readBoolean3(value) {
 function formatEnvValue3(value) {
   return /^[A-Za-z0-9_./:@-]*$/u.test(value) ? value : JSON.stringify(value);
 }
-function escapeRegExp3(value) {
+function escapeRegExp4(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
 function isNodeError16(error, code) {
@@ -21172,9 +21511,9 @@ function connectRelayControl(options) {
         return;
       }
       reconnectAttempts += 1;
-      const delay2 = computeBackoffMs(reconnectAttempts, backoffBaseMs, backoffMaxMs);
-      options.onStatus?.({ state: "retrying", attempt: reconnectAttempts, message: `Retrying in ${delay2}ms` });
-      retryTimer = setTimeout(connect, delay2);
+      const delay3 = computeBackoffMs(reconnectAttempts, backoffBaseMs, backoffMaxMs);
+      options.onStatus?.({ state: "retrying", attempt: reconnectAttempts, message: `Retrying in ${delay3}ms` });
+      retryTimer = setTimeout(connect, delay3);
       retryTimer.unref?.();
     });
   };

package/dist/cli/index.js

@@ -36,7 +36,7 @@ import {
   startDaemonProcess,
   startLinkService,
   stopDaemonProcess
-} from "../chunk-DUQDO2LQ.js";
+} from "../chunk-B42L327D.js";
 
 // src/cli/index.ts
 import { Command } from "commander";

package/dist/http/app.js

@@ -1,6 +1,6 @@
 import {
   createApp
-} from "../chunk-DUQDO2LQ.js";
+} from "../chunk-B42L327D.js";
 export {
   createApp
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hermespilot/link",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "private": false,
   "description": "Hermes Link companion service and CLI for connecting hermes-agent through HermesPilot",
   "license": "MIT",

package/scripts/postinstall.mjs

@@ -1,3 +1,5 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
 import process from "node:process";
 
 function isTruthy(value) {
@@ -14,6 +16,49 @@ function shouldPrintInstallHint() {
   return process.env.npm_config_global === "true";
 }
 
+function resolveNpmCommand() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function resolveGlobalPrefix() {
+  const envPrefix =
+    process.env.npm_config_prefix?.trim() ??
+    process.env.npm_config_global_prefix?.trim() ??
+    "";
+  if (envPrefix) {
+    return envPrefix;
+  }
+  try {
+    const output = execFileSync(resolveNpmCommand(), ["prefix", "-g"], {
+      encoding: "utf8",
+    });
+    return output.trim();
+  } catch {
+    return "";
+  }
+}
+
+function resolveGlobalBinDir(prefix) {
+  return process.platform === "win32" ? prefix : path.join(prefix, "bin");
+}
+
+function resolveHermesLinkCommandPath(binDir) {
+  return process.platform === "win32"
+    ? path.join(binDir, "hermeslink.cmd")
+    : path.join(binDir, "hermeslink");
+}
+
+function pathIncludes(target) {
+  if (!target) {
+    return false;
+  }
+  const normalizedTarget = path.resolve(target);
+  return (process.env.PATH ?? "")
+    .split(path.delimiter)
+    .filter(Boolean)
+    .some((entry) => path.resolve(entry) === normalizedTarget);
+}
+
 function detectLanguage() {
   const candidates = [
     process.env.HERMESLINK_LANG,
@@ -42,13 +87,35 @@ async function main() {
   }
 
   const language = detectLanguage();
+  const globalPrefix = resolveGlobalPrefix();
+  const globalBinDir = globalPrefix ? resolveGlobalBinDir(globalPrefix) : "";
+  const commandPath = globalBinDir ? resolveHermesLinkCommandPath(globalBinDir) : "";
+  const binOnPath = globalBinDir ? pathIncludes(globalBinDir) : false;
   console.log("");
   if (language === "zh-CN") {
     console.log("Hermes Link 已安装。");
     console.log("运行 `hermeslink pair`，把这台电脑连接到 HermesPilot App。");
+    if (globalBinDir && !binOnPath) {
+      console.log(
+        `如果当前 shell 找不到 \`hermeslink\`，说明 npm 全局 bin 目录没有进 PATH：${globalBinDir}`,
+      );
+      console.log(`你可以直接运行：${commandPath} pair`);
+      if (process.platform !== "win32") {
+        console.log(`或者先补 PATH：export PATH="${globalBinDir}:$PATH"`);
+      }
+    }
   } else {
     console.log("Hermes Link installed.");
     console.log("Run `hermeslink pair` to connect this computer with HermesPilot App.");
+    if (globalBinDir && !binOnPath) {
+      console.log(
+        `If your shell cannot find \`hermeslink\`, npm's global bin directory is not on PATH: ${globalBinDir}`,
+      );
+      console.log(`You can run it directly: ${commandPath} pair`);
+      if (process.platform !== "win32") {
+        console.log(`Or add it to PATH first: export PATH="${globalBinDir}:$PATH"`);
+      }
+    }
   }
   console.log("");
 }