@hermespilot/link 0.4.5 → 0.4.7

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-UANE2YHT.js → chunk-PRYXZRQI.js}

@@ -2080,6 +2080,14 @@ async function ensureHermesApiServerConfig(profileName = "default", configPath =
   }
   return ensureHermesApiServerConfigUnlocked(profileName, configPath);
 }
+async function repairHermesApiServerConfig(profileName = "default", configPath = resolveHermesConfigPath(profileName)) {
+  if (profileName !== "default") {
+    return withProfileApiServerPortAssignmentLock(
+      () => repairHermesApiServerConfigUnlocked(profileName, configPath)
+    );
+  }
+  return repairHermesApiServerConfigUnlocked(profileName, configPath);
+}
 async function ensureHermesApiServerConfigUnlocked(profileName = "default", configPath = resolveHermesConfigPath(profileName)) {
   const existingRaw = await readFile2(configPath, "utf8").catch(
     (error) => {
@@ -2096,47 +2104,60 @@ async function ensureHermesApiServerConfigUnlocked(profileName = "default", conf
   const extra = ensureRecord(apiServer, "extra");
   const configOnly = readApiServerConfig(apiServer);
   const envOverrides = await readHermesApiServerEnvOverrides(profileName);
-  const before = applyEnvOverrides(configOnly, envOverrides, false);
-  const beforeKey = before.key?.trim() ? before.key : null;
-  const beforeEnabled = before.enabled === true;
-  const beforeHost = before.host?.trim() ? before.host : null;
-  const beforePort = typeof before.port === "number" && Number.isFinite(before.port) ? before.port : null;
+  const configKey = configOnly.key?.trim() ? configOnly.key : null;
+  const envKey = envOverrides.key?.trim() ? envOverrides.key : null;
+  const configHost = configOnly.host?.trim() ? configOnly.host : null;
+  const envHost = envOverrides.host?.trim() ? envOverrides.host : null;
+  const configPort = readApiServerPort(configOnly.port);
+  const envPort = readApiServerPort(envOverrides.port);
+  const desiredHost = configHost ?? envHost ?? DEFAULT_HERMES_API_SERVER_HOST;
+  const desiredPort = await resolveDesiredApiServerPort({
+    profileName,
+    configPort,
+    envPort
+  });
+  const desiredKey = configKey ?? envKey ?? randomBytes(32).toString("base64url");
   let changed = false;
   let enabledAdded = false;
   let hostAdded = false;
   let portAdded = false;
-  let assignedPort = null;
-  if (!beforeEnabled) {
+  if (apiServer.enabled !== true) {
     apiServer.enabled = true;
     enabledAdded = true;
     changed = true;
   }
-  if (!beforeHost) {
-    extra.host = DEFAULT_HERMES_API_SERVER_HOST;
-    hostAdded = true;
+  if (configHost !== desiredHost) {
+    extra.host = desiredHost;
+    hostAdded = !configHost;
     changed = true;
   }
-  if (shouldAssignDedicatedProfileApiServerPort(profileName, configOnly.port)) {
-    assignedPort = await nextProfileApiServerPort(profileName);
-    extra.port = assignedPort;
-    portAdded = true;
-    changed = true;
-  } else if (!beforePort) {
-    assignedPort = DEFAULT_HERMES_API_SERVER_PORT;
-    extra.port = assignedPort;
+  if (configPort !== desiredPort) {
+    extra.port = desiredPort;
     portAdded = true;
     changed = true;
   }
-  if (!beforeKey) {
-    extra.key = randomBytes(32).toString("base64url");
+  if (configKey !== desiredKey) {
+    extra.key = desiredKey;
     changed = true;
   }
-  if (!changed) {
+  const desiredApiServer = readApiServerConfig(apiServer, true);
+  const backupPath = changed && existingRaw ? `${configPath}.bak.${Date.now()}` : null;
+  if (backupPath && existingRaw !== null) {
+    await atomicWriteFilePreservingMetadata(backupPath, existingRaw, {
+      metadataSourcePath: configPath
+    });
+  }
+  if (changed) {
+    document.contents = document.createNode(config);
+    await atomicWriteFilePreservingMetadata(configPath, document.toString());
+  }
+  const envChanged = await writeHermesApiServerEnv(profileName, desiredApiServer);
+  if (!changed && !envChanged) {
     return {
       configPath,
       apiServer: applyEnvOverrides(
         readApiServerConfig(apiServer, true),
-        envOverrides,
+        await readHermesApiServerEnvOverrides(profileName),
         true
       ),
       changed: false,
@@ -2148,36 +2169,79 @@ async function ensureHermesApiServerConfigUnlocked(profileName = "default", conf
       notice: null
     };
   }
-  const backupPath = existingRaw ? `${configPath}.bak.${Date.now()}` : null;
-  if (backupPath && existingRaw !== null) {
-    await atomicWriteFilePreservingMetadata(backupPath, existingRaw, {
-      metadataSourcePath: configPath
-    });
-  }
-  document.contents = document.createNode(config);
-  await atomicWriteFilePreservingMetadata(configPath, document.toString());
   return {
     configPath,
     apiServer: applyEnvOverrides(
       readApiServerConfig(apiServer, true),
-      envOverrides,
+      await readHermesApiServerEnvOverrides(profileName),
       true
     ),
     changed: true,
-    keyAdded: !beforeKey,
+    keyAdded: !configKey,
     enabledAdded,
     hostAdded,
     portAdded,
     backupPath,
     notice: buildNotice({
-      keyAdded: !beforeKey,
+      keyAdded: !configKey,
       enabledAdded,
       hostAdded,
       portAdded,
-      port: assignedPort ?? beforePort ?? void 0
+      port: desiredPort
     })
   };
 }
+async function repairHermesApiServerConfigUnlocked(profileName = "default", configPath = resolveHermesConfigPath(profileName)) {
+  const existingRaw = await readFile2(configPath, "utf8").catch(
+    (error) => {
+      if (isNodeError3(error, "ENOENT")) {
+        return null;
+      }
+      throw error;
+    }
+  );
+  const document = existingRaw ? YAML.parseDocument(existingRaw) : new YAML.Document({});
+  const config = toRecord(document.toJSON());
+  const platforms = ensureRecord(config, "platforms");
+  const apiServer = ensureRecord(platforms, "api_server");
+  const extra = ensureRecord(apiServer, "extra");
+  const previous = applyEnvOverrides(
+    readApiServerConfig(apiServer, true),
+    await readHermesApiServerEnvOverrides(profileName),
+    true
+  );
+  const freshPort = await nextProfileApiServerPort(profileName);
+  const freshKey = randomBytes(32).toString("base64url");
+  apiServer.enabled = true;
+  extra.host = DEFAULT_HERMES_API_SERVER_HOST;
+  extra.port = freshPort;
+  extra.key = freshKey;
+  const backupPath = existingRaw ? `${configPath}.bak.${Date.now()}` : null;
+  if (backupPath && existingRaw !== null) {
+    await atomicWriteFilePreservingMetadata(backupPath, existingRaw, {
+      metadataSourcePath: configPath
+    });
+  }
+  document.contents = document.createNode(config);
+  await atomicWriteFilePreservingMetadata(configPath, document.toString());
+  const apiServerConfig = readApiServerConfig(apiServer, true);
+  await writeHermesApiServerEnv(profileName, apiServerConfig, { force: true });
+  return {
+    configPath,
+    apiServer: applyEnvOverrides(
+      apiServerConfig,
+      await readHermesApiServerEnvOverrides(profileName),
+      true
+    ),
+    changed: true,
+    keyAdded: !previous.key,
+    enabledAdded: previous.enabled !== true,
+    hostAdded: previous.host !== DEFAULT_HERMES_API_SERVER_HOST,
+    portAdded: previous.port !== freshPort,
+    backupPath,
+    notice: "\u5DF2\u4E3A Hermes API Server \u91CD\u65B0\u5206\u914D\u672C\u673A\u7AEF\u53E3\u5E76\u8F6E\u6362 key\uFF0C\u7528\u4E8E\u4FEE\u590D\u65E7 Gateway \u6216 key \u4E0D\u4E00\u81F4\u5BFC\u81F4\u7684 401\u3002"
+  };
+}
 async function readHermesConfigDocument(configPath) {
   const existingRaw = await readFile2(configPath, "utf8").catch(
     (error) => {
@@ -3511,6 +3575,21 @@ function shouldAssignDedicatedProfileApiServerPort(profileName, configuredPort)
   }
   return configuredPort === void 0 || configuredPort === DEFAULT_HERMES_API_SERVER_PORT;
 }
+function readApiServerPort(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+}
+async function resolveDesiredApiServerPort(input) {
+  if (shouldAssignDedicatedProfileApiServerPort(
+    input.profileName,
+    input.configPort ?? void 0
+  )) {
+    if (input.profileName !== "default" && input.envPort !== null && input.envPort !== DEFAULT_HERMES_API_SERVER_PORT) {
+      return input.envPort;
+    }
+    return nextProfileApiServerPort(input.profileName);
+  }
+  return input.configPort ?? input.envPort ?? DEFAULT_HERMES_API_SERVER_PORT;
+}
 async function nextProfileApiServerPort(profileName) {
   const usedPorts = await readConfiguredApiServerPorts(profileName);
   for (let port = PROFILE_API_SERVER_PORT_START; port <= PROFILE_API_SERVER_PORT_END; port += 1) {
@@ -3670,14 +3749,82 @@ async function writeHermesEnvValue(profileName, key, value) {
   }
   await atomicWriteFilePreservingMetadata(envPath, nextRaw);
 }
+async function writeHermesApiServerEnv(profileName, config, options = {}) {
+  const envPath = path3.join(resolveHermesProfileDir(profileName), ".env");
+  const existingRaw = await readFile2(envPath, "utf8").catch(
+    (error) => {
+      if (isNodeError3(error, "ENOENT")) {
+        return null;
+      }
+      throw error;
+    }
+  );
+  if (existingRaw === null && profileName === "default" && !options.force) {
+    return false;
+  }
+  return writeHermesEnvValues(
+    profileName,
+    [
+      ["API_SERVER_ENABLED", config.enabled === false ? "false" : "true"],
+      ["API_SERVER_HOST", config.host ?? DEFAULT_HERMES_API_SERVER_HOST],
+      ["API_SERVER_PORT", String(config.port ?? DEFAULT_HERMES_API_SERVER_PORT)],
+      ["API_SERVER_KEY", config.key ?? ""]
+    ],
+    existingRaw ?? ""
+  );
+}
+async function writeHermesEnvValues(profileName, values, existingRaw) {
+  const envPath = path3.join(resolveHermesProfileDir(profileName), ".env");
+  const raw = existingRaw ?? await readFile2(envPath, "utf8").catch((error) => {
+    if (isNodeError3(error, "ENOENT")) {
+      return "";
+    }
+    throw error;
+  });
+  const lines = raw ? raw.split(/\r?\n/u) : [];
+  const remaining = new Map(values);
+  const nextLines = lines.map((line) => {
+    const trimmed = line.trim();
+    for (const [key, value] of remaining) {
+      const keyPattern = new RegExp(
+        `^(?:export\\s+)?${escapeRegExp(key)}=`,
+        "u"
+      );
+      if (keyPattern.test(trimmed)) {
+        remaining.delete(key);
+        return `${key}=${formatEnvValue(value)}`;
+      }
+    }
+    return line;
+  });
+  if (remaining.size > 0 && nextLines.length > 0 && nextLines.at(-1) !== "") {
+    nextLines.push("");
+  }
+  for (const [key, value] of remaining) {
+    nextLines.push(`${key}=${formatEnvValue(value)}`);
+  }
+  const nextRaw = nextLines.join("\n").replace(/\n*$/u, "\n");
+  if (nextRaw === raw) {
+    return false;
+  }
+  if (raw) {
+    await atomicWriteFilePreservingMetadata(
+      `${envPath}.bak.${Date.now()}`,
+      raw,
+      { metadataSourcePath: envPath }
+    );
+  }
+  await atomicWriteFilePreservingMetadata(envPath, nextRaw);
+  return true;
+}
 function applyEnvOverrides(config, env, withDefaults) {
-  const host = config.host ?? env.host;
-  const port = config.port ?? env.port;
+  const host = env.host ?? config.host;
+  const port = env.port ?? config.port;
   return {
-    enabled: config.enabled ?? env.enabled,
+    enabled: env.enabled ?? config.enabled,
     host: withDefaults ? host ?? DEFAULT_HERMES_API_SERVER_HOST : host,
     port: withDefaults ? port ?? DEFAULT_HERMES_API_SERVER_PORT : port,
-    key: config.key ?? env.key
+    key: env.key ?? config.key
   };
 }
 function parseEnvBoolean(value) {
@@ -3985,7 +4132,7 @@ import os2 from "os";
 import path5 from "path";
 
 // src/constants.ts
-var LINK_VERSION = "0.4.5";
+var LINK_VERSION = "0.4.7";
 var LINK_COMMAND = "hermeslink";
 var LINK_DEFAULT_PORT = 52379;
 var LINK_RUNTIME_DIR_NAME = ".hermeslink";
@@ -4548,6 +4695,47 @@ async function ensureHermesApiServerAvailable(options = {}) {
     });
     return { available: true, configResult, started: true, start, health };
   }
+  if (health.authInvalid) {
+    void options.logger?.warn("gateway_api_server_auth_repair_requested", {
+      profile: profileName,
+      port: configResult.apiServer.port ?? null,
+      issue: health.issue ?? "auth_invalid"
+    });
+    const repairedConfigResult = await repairHermesApiServerConfig(profileName);
+    const repairedStart = await startHermesGatewayOnce(
+      options.paths ?? resolveRuntimePaths(),
+      profileName,
+      options.logger
+    );
+    health = await waitForHermesApiHealth(
+      repairedConfigResult.apiServer,
+      fetcher,
+      options.timeoutMs ?? DEFAULT_START_TIMEOUT_MS
+    );
+    if (health.healthy) {
+      void options.logger?.info("gateway_api_server_auth_repair_succeeded", {
+        profile: profileName,
+        pid: repairedStart.pid,
+        port: repairedConfigResult.apiServer.port ?? null,
+        log_path: repairedStart.logPath,
+        hermes_version: repairedStart.version?.version ?? null
+      });
+      return {
+        available: true,
+        configResult: repairedConfigResult,
+        started: true,
+        start: repairedStart,
+        health
+      };
+    }
+    void options.logger?.error("gateway_api_server_auth_repair_failed", {
+      profile: profileName,
+      pid: repairedStart.pid,
+      port: repairedConfigResult.apiServer.port ?? null,
+      log_path: repairedStart.logPath,
+      issue: health.issue ?? "unknown"
+    });
+  }
   const logHint = await readRecentGatewayLogHint(start.logPath);
   void options.logger?.error("gateway_auto_start_failed", {
     profile: profileName,
@@ -4638,12 +4826,9 @@ async function readHermesVersion(options = {}) {
 }
 async function execHermesVersion(hermesBin, logger) {
   const failures = [];
-  for (const args of [["version"], ["--version"]]) {
+  for (const args of [["--version"], ["version"]]) {
     try {
-      return await execFileAsync2(hermesBin, args, {
-        timeout: 5e3,
-        windowsHide: true
-      });
+      return await spawnHermesVersionCommand(hermesBin, args, 5e3);
     } catch (error) {
       const failure = describeVersionCommandFailure(hermesBin, args, error);
       failures.push(failure);
@@ -4659,6 +4844,85 @@ async function execHermesVersion(hermesBin, logger) {
   });
   throw new Error(summary);
 }
+async function spawnHermesVersionCommand(hermesBin, args, timeoutMs) {
+  return await new Promise((resolve, reject) => {
+    const child = spawn(hermesBin, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const timer = setTimeout(() => {
+      finish(() => {
+        reject(
+          createVersionCommandError(
+            `${hermesBin} ${args.join(" ")} 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();
+    };
+    const resolveIfVersionPrinted = () => {
+      if (parseHermesVersion(stdout)) {
+        finish(() => resolve({ stdout: `${stdout}
+${stderr}`.trim() }), true);
+      }
+    };
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+      resolveIfVersionPrinted();
+    });
+    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();
+        const version = parseHermesVersion(raw);
+        if (code === 0 && (raw || version)) {
+          resolve({ stdout: raw });
+          return;
+        }
+        reject(
+          createVersionCommandError(
+            `${hermesBin} ${args.join(" ")} exited with code ${code ?? "null"}`,
+            {
+              stdout,
+              stderr,
+              code,
+              signal,
+              killed: child.killed
+            }
+          )
+        );
+      });
+    });
+  });
+}
 function assertHermesRunsApiSupported(version, status) {
   if (status !== 404) {
     return;
@@ -4916,11 +5180,9 @@ async function readHermesApiServerHealth(config, fetcher = fetch) {
         detailed: record
       };
     }
-    if (resolvedConfig.key) {
-      const authIssue = await probeHermesApiServerAuth(resolvedConfig, fetcher);
-      if (authIssue) {
-        return authIssue;
-      }
+    const authIssue = await probeHermesApiServerAuth(resolvedConfig, fetcher);
+    if (authIssue) {
+      return authIssue;
     }
     return { healthy: true };
   }
@@ -4937,9 +5199,6 @@ async function readHermesApiServerHealth(config, fetcher = fetch) {
   };
 }
 async function probeHermesApiServerAuth(config, fetcher) {
-  if (!config.key) {
-    return null;
-  }
   const response = await fetchWithTimeout(
     `http://127.0.0.1:${config.port}/v1/models`,
     {
@@ -5150,6 +5409,21 @@ async function probeHermesVersion(hermesBin, options) {
     }
   }
 }
+function createVersionCommandError(message, details) {
+  const error = new Error(message, { cause: details.cause });
+  error.stdout = details.stdout;
+  error.stderr = details.stderr;
+  if (details.code !== void 0) {
+    error.code = details.code;
+  }
+  if (details.signal !== void 0) {
+    error.signal = details.signal;
+  }
+  if (details.killed !== void 0) {
+    error.killed = details.killed;
+  }
+  return error;
+}
 function describeVersionCommandFailure(hermesBin, args, error) {
   const message = error instanceof Error ? error.message : String(error);
   const details = readExecErrorDetails(error, message);
@@ -7597,12 +7871,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) {
@@ -11745,6 +12019,46 @@ async function callHermesApi(path26, init, options) {
     startedAt,
     response
   );
+  if (response.status !== 401) {
+    return response;
+  }
+  void options.logger?.warn("hermes_api_request_repairing_after_401", {
+    method,
+    path: path26,
+    profile: options.profileName ?? "default",
+    port: config.port ?? null,
+    duration_ms: Date.now() - startedAt
+  });
+  const profileName = options.profileName ?? "default";
+  const repairedConfig = await repairHermesApiServerConfig(profileName);
+  const repairedAvailability = await ensureHermesApiServerAvailable({
+    fetchImpl: options.fetchImpl,
+    forceRestart: true,
+    logger: options.logger,
+    profileName
+  });
+  config = repairedAvailability.configResult.apiServer ?? repairedConfig.apiServer;
+  try {
+    response = await request();
+  } catch (error) {
+    logHermesApiError(
+      options.logger,
+      method,
+      path26,
+      options.profileName,
+      startedAt,
+      error
+    );
+    throw error;
+  }
+  logHermesApiResponse(
+    options.logger,
+    method,
+    path26,
+    options.profileName,
+    startedAt,
+    response
+  );
   return response;
 }
 async function fetchHermesApi(fetcher, config, path26, init, options) {
@@ -16025,11 +16339,19 @@ function createHttpErrorMiddleware(logger) {
 }
 
 // src/hermes/profiles.ts
-import { readdir as readdir9, readFile as readFile12, rename as rename3, rm as rm6, stat as stat12 } from "fs/promises";
+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();
   profiles.set(DEFAULT_PROFILE, await profileInfo(DEFAULT_PROFILE, paths));
@@ -16101,12 +16423,7 @@ async function updateHermesProfileMetadata(name, metadata, paths = resolveRuntim
 async function deleteHermesProfile(name, paths = resolveRuntimePaths()) {
   assertMutableProfile(name);
   const profile = await profileInfo(name, paths);
-  const exists = await stat12(profile.path).then((value) => value.isDirectory()).catch((error) => {
-    if (isNodeError14(error, "ENOENT")) {
-      return false;
-    }
-    throw error;
-  });
+  const exists = await pathExists(profile.path);
   if (!exists) {
     throw new LinkHttpError(
       404,
@@ -16114,7 +16431,14 @@ async function deleteHermesProfile(name, paths = resolveRuntimePaths()) {
       `Profile "${name}" does not exist`
     );
   }
-  await rm6(resolveHermesProfileDir(name), { recursive: true, force: true });
+  await deleteHermesProfileWithCliAndVerify(name, profile.path);
+  if (!await waitForProfilePathToRemainAbsent(profile.path)) {
+    throw new LinkHttpError(
+      502,
+      "hermes_profile_delete_incomplete",
+      `Hermes CLI reported success, but Profile "${name}" still exists at ${profile.path}`
+    );
+  }
   await deleteProfileIdentity(paths, {
     profileName: profile.name,
     profileUid: profile.uid
@@ -16170,9 +16494,168 @@ function assertProfileName(name) {
     throw new LinkHttpError(400, "invalid_profile_name", "invalid profile name");
   }
 }
+async function pathExists(targetPath) {
+  return await stat12(targetPath).then(() => true).catch((error) => {
+    if (isNodeError14(error, "ENOENT")) {
+      return false;
+    }
+    throw error;
+  });
+}
+async function deleteHermesProfileWithCli(name) {
+  try {
+    await execFileAsync4(resolveHermesBin(), ["profile", "delete", name, "--yes"], {
+      timeout: PROFILE_DELETE_TIMEOUT_MS,
+      windowsHide: true
+    });
+  } catch (error) {
+    throw new LinkHttpError(
+      502,
+      "hermes_profile_delete_failed",
+      `Hermes CLI could not delete Profile "${name}": ${formatExecError(error)}`
+    );
+  }
+}
+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);
+  }
+  const output = readExecErrorOutput2(error);
+  return output ? `${error.message}
+${output}` : error.message;
+}
+function readExecErrorOutput2(error) {
+  const parts = [];
+  if ("stdout" in error && error.stdout != null) {
+    const stdout = String(error.stdout).trim();
+    if (stdout) {
+      parts.push(stdout);
+    }
+  }
+  if ("stderr" in error && error.stderr != null) {
+    const stderr = String(error.stderr).trim();
+    if (stderr) {
+      parts.push(stderr);
+    }
+  }
+  return parts.join("\n");
+}
 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) => {
@@ -16883,7 +17366,7 @@ import {
   cp,
   mkdir as mkdir10,
   readFile as readFile13,
-  rm as rm7,
+  rm as rm6,
   stat as stat13
 } from "fs/promises";
 import path19 from "path";
@@ -17184,7 +17667,7 @@ async function generateProfileName(displayName, paths) {
   for (let attempt = 0; attempt < 100; attempt += 1) {
     const suffix = randomSuffix(attempt);
     const candidate = `${base}-${suffix}`.slice(0, 64).replace(/[-_]+$/u, "");
-    if (!existing.has(candidate) && !await pathExists(resolveHermesProfileDir(candidate))) {
+    if (!existing.has(candidate) && !await pathExists2(resolveHermesProfileDir(candidate))) {
       return candidate;
     }
   }
@@ -17210,7 +17693,7 @@ function randomSuffix(attempt) {
 }
 async function applyProfileCreationPostSteps(input) {
   const profilePath = resolveHermesProfileDir(input.profileName);
-  if (!await pathExists(profilePath)) {
+  if (!await pathExists2(profilePath)) {
     await ensureDirectoryWithInheritedMetadata(profilePath, 448);
   }
   if (input.sourceProfile && input.copyScopes.length > 0) {
@@ -17349,7 +17832,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)}`;
@@ -17376,10 +17859,10 @@ async function writeEnvValues(profileName, values) {
 async function copySkills(sourceProfile, targetProfile) {
   const sourceSkills = path19.join(resolveHermesProfileDir(sourceProfile), "skills");
   const targetSkills = path19.join(resolveHermesProfileDir(targetProfile), "skills");
-  if (!await pathExists(sourceSkills)) {
+  if (!await pathExists2(sourceSkills)) {
     return;
   }
-  await rm7(targetSkills, { recursive: true, force: true });
+  await rm6(targetSkills, { recursive: true, force: true });
   await cp(sourceSkills, targetSkills, {
     recursive: true,
     force: true,
@@ -17427,7 +17910,7 @@ async function failProfileCreation(input) {
     await input.writer.write(`
 Rolling back ${input.rollbackProfileName}...
 `);
-    await rm7(resolveHermesProfileDir(input.rollbackProfileName), {
+    await rm6(resolveHermesProfileDir(input.rollbackProfileName), {
       recursive: true,
       force: true
     }).catch(() => void 0);
@@ -17478,14 +17961,14 @@ function profileCreationLogPath(paths) {
 async function clearProfileCreationLogFiles(paths) {
   const primary = profileCreationLogPath(paths);
   await Promise.all([
-    rm7(primary, { force: true }).catch(() => void 0),
+    rm6(primary, { force: true }).catch(() => void 0),
     ...Array.from(
       { length: PROFILE_CREATE_LOG_MAX_FILES },
-      (_, index) => rm7(`${primary}.${index + 1}`, { force: true }).catch(() => void 0)
+      (_, index) => rm6(`${primary}.${index + 1}`, { force: true }).catch(() => void 0)
     )
   ]);
 }
-async function pathExists(targetPath) {
+async function pathExists2(targetPath) {
   return await stat13(targetPath).then(() => true).catch((error) => {
     if (isNodeError15(error, "ENOENT")) {
       return false;
@@ -17531,7 +18014,7 @@ function formatEnvValue2(value) {
   }
   return JSON.stringify(value);
 }
-function escapeRegExp2(value) {
+function escapeRegExp3(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
 function isNodeError15(error, code) {
@@ -18860,7 +19343,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())) {
@@ -19081,7 +19564,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) {
@@ -20337,7 +20820,7 @@ function readModelList(payload) {
 // src/hermes/updates.ts
 import { EventEmitter as EventEmitter3 } from "events";
 import { spawn as spawn3 } from "child_process";
-import { mkdir as mkdir11, readFile as readFile16, rm as rm8 } from "fs/promises";
+import { mkdir as mkdir11, readFile as readFile16, rm as rm7 } from "fs/promises";
 import path22 from "path";
 var SERVER_HERMES_RELEASES_LATEST_PATH = "/api/v1/hermes-agent/releases/latest";
 var RELEASE_CACHE_TTL_MS = 6 * 60 * 60 * 1e3;
@@ -20627,10 +21110,10 @@ function updateLogPath(paths) {
 async function clearUpdateLogFiles(paths) {
   const primary = updateLogPath(paths);
   await Promise.all([
-    rm8(primary, { force: true }).catch(() => void 0),
+    rm7(primary, { force: true }).catch(() => void 0),
     ...Array.from(
       { length: UPDATE_LOG_MAX_FILES },
-      (_, index) => rm8(`${primary}.${index + 1}`, { force: true }).catch(() => void 0)
+      (_, index) => rm7(`${primary}.${index + 1}`, { force: true }).catch(() => void 0)
     )
   ]);
 }
@@ -20722,17 +21205,17 @@ function readString17(payload, key) {
 // src/link/updates.ts
 import { spawn as spawn5 } from "child_process";
 import { EventEmitter as EventEmitter4 } from "events";
-import { mkdir as mkdir14, readFile as readFile18, rm as rm11 } from "fs/promises";
+import { mkdir as mkdir14, readFile as readFile18, rm as rm10 } from "fs/promises";
 import path24 from "path";
 
 // src/daemon/process.ts
 import { spawn as spawn4 } from "child_process";
-import { mkdir as mkdir13, readFile as readFile17, rm as rm10 } from "fs/promises";
+import { mkdir as mkdir13, readFile as readFile17, rm as rm9 } from "fs/promises";
 import path23 from "path";
 
 // src/daemon/service.ts
 import { createServer } from "http";
-import { mkdir as mkdir12, rm as rm9, writeFile as writeFile3 } from "fs/promises";
+import { mkdir as mkdir12, rm as rm8, writeFile as writeFile3 } from "fs/promises";
 
 // src/relay/control-client.ts
 import WebSocket from "ws";
@@ -20806,9 +21289,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?.();
     });
   };
@@ -21845,7 +22328,7 @@ async function startLinkService(options = {}) {
       await logger.info("service_stopped");
       await logger.flush();
       if (options.writePidFile) {
-        await rm9(pidFilePath(paths), { force: true }).catch(() => void 0);
+        await rm8(pidFilePath(paths), { force: true }).catch(() => void 0);
       }
     }
   };
@@ -22037,7 +22520,7 @@ async function stopDaemonProcess(paths = resolveRuntimePaths()) {
   try {
     process.kill(status.pid, "SIGTERM");
   } catch {
-    await rm10(pidFilePath(paths), { force: true }).catch(() => void 0);
+    await rm9(pidFilePath(paths), { force: true }).catch(() => void 0);
     return await getDaemonStatus(paths);
   }
   for (let index = 0; index < 20; index += 1) {
@@ -22059,7 +22542,7 @@ async function stopDaemonProcess(paths = resolveRuntimePaths()) {
     }
   }
   if (!isProcessAlive3(status.pid) || !await pidBackedServiceIsReachable(paths)) {
-    await rm10(pidFilePath(paths), { force: true }).catch(() => void 0);
+    await rm9(pidFilePath(paths), { force: true }).catch(() => void 0);
   }
   return await getDaemonStatus(paths);
 }
@@ -22067,7 +22550,7 @@ async function getDaemonStatus(paths = resolveRuntimePaths()) {
   const pidFile = pidFilePath(paths);
   const pid = await readPid(pidFile);
   if (pid && !isProcessAlive3(pid)) {
-    await rm10(pidFile, { force: true }).catch(() => void 0);
+    await rm9(pidFile, { force: true }).catch(() => void 0);
     return {
       running: false,
       pid: null,
@@ -22522,10 +23005,10 @@ function updateLogPath2(paths) {
 async function clearUpdateLogFiles2(paths) {
   const primary = updateLogPath2(paths);
   await Promise.all([
-    rm11(primary, { force: true }).catch(() => void 0),
+    rm10(primary, { force: true }).catch(() => void 0),
     ...Array.from(
       { length: UPDATE_LOG_MAX_FILES2 },
-      (_, index) => rm11(`${primary}.${index + 1}`, { force: true }).catch(() => void 0)
+      (_, index) => rm10(`${primary}.${index + 1}`, { force: true }).catch(() => void 0)
     )
   ]);
 }
@@ -22582,7 +23065,7 @@ function readString18(payload, key) {
 
 // src/pairing/pairing.ts
 import path25 from "path";
-import { rm as rm12 } from "fs/promises";
+import { rm as rm11 } from "fs/promises";
 
 // src/relay/bootstrap.ts
 var RelayNetworkError = class extends Error {
@@ -22844,7 +23327,7 @@ async function readPairingClaim(sessionId, paths = resolveRuntimePaths()) {
   };
 }
 async function clearPairingClaim(sessionId, paths = resolveRuntimePaths()) {
-  await rm12(pairingClaimPath(sessionId, paths), { force: true }).catch(() => void 0);
+  await rm11(pairingClaimPath(sessionId, paths), { force: true }).catch(() => void 0);
 }
 async function claimPairing(input) {
   const paths = input.paths ?? resolveRuntimePaths();

package/dist/cli/index.js

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

package/dist/http/app.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hermespilot/link",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "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("");
 }