@hermespilot/link 0.1.6 → 0.1.8

package/dist/{chunk-VCQJ5DSN.js → chunk-L2NM2XMX.js}

@@ -4,7 +4,7 @@ import Router from "@koa/router";
 import { Readable } from "stream";
 
 // src/constants.ts
-var LINK_VERSION = "0.1.6";
+var LINK_VERSION = "0.1.8";
 var LINK_COMMAND = "hermeslink";
 var LINK_DEFAULT_PORT = 52379;
 var LINK_RUNTIME_DIR_NAME = ".hermeslink";
@@ -96,12 +96,30 @@ function normalizeConfiguredLanguage(language) {
 
 // src/conversations/conversation-service.ts
 import { EventEmitter } from "events";
-import { appendFile, mkdir as mkdir3, readdir, readFile as readFile3, rm as rm2, stat, writeFile as writeFile2 } from "fs/promises";
-import path4 from "path";
-import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { appendFile, mkdir as mkdir4, readdir, readFile as readFile3, rm as rm2, stat, writeFile as writeFile2 } from "fs/promises";
+import path5 from "path";
+import { createHash, randomUUID } from "crypto";
 
-// src/hermes/api-server.ts
-import { randomUUID } from "crypto";
+// src/http/errors.ts
+var LinkHttpError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+  status;
+  code;
+};
+function isLinkHttpError(error) {
+  return error instanceof LinkHttpError;
+}
+
+// src/hermes/gateway.ts
+import { execFile as execFile2, spawn } from "child_process";
+import { mkdir as mkdir3, open as open2 } from "fs/promises";
+import path4 from "path";
+import { setTimeout as delay } from "timers/promises";
+import { promisify as promisify2 } from "util";
 
 // src/hermes/config.ts
 import { randomBytes } from "crypto";
@@ -109,6 +127,8 @@ import { copyFile, mkdir as mkdir2, readFile as readFile2, writeFile } from "fs/
 import os2 from "os";
 import path3 from "path";
 import YAML from "yaml";
+var DEFAULT_HERMES_API_SERVER_HOST = "127.0.0.1";
+var DEFAULT_HERMES_API_SERVER_PORT = 8642;
 function resolveHermesProfileDir(profileName = "default") {
   if (profileName === "default") {
     return path3.join(os2.homedir(), ".hermes");
@@ -126,14 +146,21 @@ async function readHermesApiServerConfig(profileName = "default", configPath = r
     throw error;
   });
   if (!existingRaw) {
-    return {};
+    return applyEnvOverrides({}, await readHermesApiServerEnvOverrides(profileName), false);
   }
   const config = toRecord(YAML.parse(existingRaw));
   const platforms = toRecord(config.platforms);
   const apiServer = toRecord(platforms.api_server);
-  return readApiServerConfig(toRecord(apiServer.extra));
+  return applyEnvOverrides(
+    readApiServerConfig(apiServer, true),
+    await readHermesApiServerEnvOverrides(profileName),
+    true
+  );
 }
 async function ensureHermesApiServerKey(profileName = "default", configPath = resolveHermesConfigPath(profileName)) {
+  return ensureHermesApiServerConfig(profileName, configPath);
+}
+async function ensureHermesApiServerConfig(profileName = "default", configPath = resolveHermesConfigPath(profileName)) {
   const existingRaw = await readFile2(configPath, "utf8").catch((error) => {
     if (isNodeError2(error, "ENOENT")) {
       return null;
@@ -145,8 +172,31 @@ async function ensureHermesApiServerKey(profileName = "default", configPath = re
   const platforms = ensureRecord(config, "platforms");
   const apiServer = ensureRecord(platforms, "api_server");
   const extra = ensureRecord(apiServer, "extra");
-  const beforeKey = typeof extra.key === "string" && extra.key.length > 0 ? extra.key : null;
+  const envOverrides = await readHermesApiServerEnvOverrides(profileName);
+  const before = applyEnvOverrides(readApiServerConfig(apiServer), 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;
   let changed = false;
+  let enabledAdded = false;
+  let hostAdded = false;
+  let portAdded = false;
+  if (!beforeEnabled) {
+    apiServer.enabled = true;
+    enabledAdded = true;
+    changed = true;
+  }
+  if (!beforeHost) {
+    extra.host = DEFAULT_HERMES_API_SERVER_HOST;
+    hostAdded = true;
+    changed = true;
+  }
+  if (!beforePort) {
+    extra.port = DEFAULT_HERMES_API_SERVER_PORT;
+    portAdded = true;
+    changed = true;
+  }
   if (!beforeKey) {
     extra.key = randomBytes(32).toString("base64url");
     changed = true;
@@ -154,9 +204,12 @@ async function ensureHermesApiServerKey(profileName = "default", configPath = re
   if (!changed) {
     return {
       configPath,
-      apiServer: readApiServerConfig(extra),
+      apiServer: applyEnvOverrides(readApiServerConfig(apiServer, true), envOverrides, true),
       changed: false,
       keyAdded: false,
+      enabledAdded: false,
+      hostAdded: false,
+      portAdded: false,
       backupPath: null,
       notice: null
     };
@@ -170,20 +223,111 @@ async function ensureHermesApiServerKey(profileName = "default", configPath = re
   await writeFile(configPath, document.toString(), { mode: 384 });
   return {
     configPath,
-    apiServer: readApiServerConfig(extra),
+    apiServer: applyEnvOverrides(readApiServerConfig(apiServer, true), envOverrides, true),
     changed: true,
-    keyAdded: true,
+    keyAdded: !beforeKey,
+    enabledAdded,
+    hostAdded,
+    portAdded,
     backupPath,
-    notice: "\u5DF2\u4E3A Hermes API Server \u81EA\u52A8\u8865\u5145 key\uFF1B\u672A\u8986\u76D6\u5DF2\u6709 port/host/key\u3002"
+    notice: buildNotice({ keyAdded: !beforeKey, enabledAdded, hostAdded, portAdded })
   };
 }
-function readApiServerConfig(extra) {
+function readApiServerConfig(apiServerOrExtra, withDefaults = false) {
+  const apiServer = "extra" in apiServerOrExtra ? apiServerOrExtra : {};
+  const extra = toRecord("extra" in apiServerOrExtra ? apiServerOrExtra.extra : apiServerOrExtra);
+  const port = typeof extra.port === "number" ? extra.port : void 0;
+  const host = typeof extra.host === "string" ? extra.host : void 0;
   return {
-    host: typeof extra.host === "string" ? extra.host : void 0,
-    port: typeof extra.port === "number" ? extra.port : void 0,
+    enabled: apiServer.enabled === true,
+    host: withDefaults ? host ?? DEFAULT_HERMES_API_SERVER_HOST : host,
+    port: withDefaults ? port ?? DEFAULT_HERMES_API_SERVER_PORT : port,
     key: typeof extra.key === "string" ? extra.key : void 0
   };
 }
+async function readHermesApiServerEnvOverrides(profileName) {
+  const values = await readHermesEnvFile(profileName);
+  for (const key of ["API_SERVER_ENABLED", "API_SERVER_HOST", "API_SERVER_PORT", "API_SERVER_KEY"]) {
+    const value = process.env[key];
+    if (typeof value === "string" && value.trim()) {
+      values[key] = value;
+    }
+  }
+  const port = Number.parseInt(values.API_SERVER_PORT ?? "", 10);
+  return {
+    enabled: parseEnvBoolean(values.API_SERVER_ENABLED),
+    host: values.API_SERVER_HOST?.trim() || void 0,
+    port: Number.isFinite(port) ? port : void 0,
+    key: values.API_SERVER_KEY?.trim() || void 0
+  };
+}
+async function readHermesEnvFile(profileName) {
+  const envPath = path3.join(resolveHermesProfileDir(profileName), ".env");
+  const raw = await readFile2(envPath, "utf8").catch((error) => {
+    if (isNodeError2(error, "ENOENT")) {
+      return "";
+    }
+    throw error;
+  });
+  const values = {};
+  for (const line of raw.split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    const match = /^(?:export\s+)?(?<key>[A-Za-z_][A-Za-z0-9_]*)=(?<value>.*)$/u.exec(trimmed);
+    if (!match?.groups) {
+      continue;
+    }
+    values[match.groups.key] = unquoteEnvValue(match.groups.value.trim());
+  }
+  return values;
+}
+function applyEnvOverrides(config, env, withDefaults) {
+  const host = env.host ?? config.host;
+  const port = env.port ?? config.port;
+  return {
+    enabled: env.enabled ?? config.enabled,
+    host: withDefaults ? host ?? DEFAULT_HERMES_API_SERVER_HOST : host,
+    port: withDefaults ? port ?? DEFAULT_HERMES_API_SERVER_PORT : port,
+    key: env.key ?? config.key
+  };
+}
+function parseEnvBoolean(value) {
+  if (!value) {
+    return void 0;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) {
+    return true;
+  }
+  if (["0", "false", "no", "off"].includes(normalized)) {
+    return false;
+  }
+  return void 0;
+}
+function unquoteEnvValue(value) {
+  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+function buildNotice(flags) {
+  const fields = [];
+  if (flags.enabledAdded) {
+    fields.push("enabled");
+  }
+  if (flags.hostAdded) {
+    fields.push("host=127.0.0.1");
+  }
+  if (flags.portAdded) {
+    fields.push("port=8642");
+  }
+  if (flags.keyAdded) {
+    fields.push("key");
+  }
+  return `\u5DF2\u4E3A Hermes API Server \u81EA\u52A8\u8865\u5145 ${fields.join("\u3001")}\uFF1B\u672A\u8986\u76D6\u5DF2\u6709 port/host/key\u3002`;
+}
 function toRecord(value) {
   return typeof value === "object" && value !== null ? value : {};
 }
@@ -200,22 +344,199 @@ function isNodeError2(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 
-// src/http/errors.ts
-var LinkHttpError = class extends Error {
-  constructor(status, code, message) {
-    super(message);
-    this.status = status;
-    this.code = code;
+// src/hermes/cli.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+async function deleteHermesSession(sessionId) {
+  if (!sessionId.trim()) {
+    throw new LinkHttpError(400, "hermes_session_id_required", "Hermes session id is required");
   }
-  status;
-  code;
-};
-function isLinkHttpError(error) {
-  return error instanceof LinkHttpError;
+  try {
+    await execFileAsync(resolveHermesBin(), ["sessions", "delete", sessionId, "--yes"], {
+      timeout: 1e4,
+      windowsHide: true
+    });
+  } catch (error) {
+    throw new LinkHttpError(
+      502,
+      "hermes_session_delete_failed",
+      error instanceof Error ? error.message : "Hermes session delete failed"
+    );
+  }
+}
+function resolveHermesBin() {
+  return process.env.HERMES_BIN?.trim() || "hermes";
+}
+
+// src/hermes/gateway.ts
+var execFileAsync2 = promisify2(execFile2);
+var DEFAULT_START_TIMEOUT_MS = 12e3;
+var HEALTH_TIMEOUT_MS = 1500;
+var MIN_API_SERVER_VERSION = "0.4.0";
+var gatewayStartInFlight = null;
+async function ensureHermesApiServerAvailable(options = {}) {
+  const configResult = await ensureHermesApiServerConfig();
+  const fetcher = options.fetchImpl ?? fetch;
+  if (!options.forceRestart && await isHermesApiHealthy(configResult.apiServer, fetcher)) {
+    return { available: true, configResult, started: false };
+  }
+  if (!shouldAutoStart(options.autoStart)) {
+    throw new LinkHttpError(503, "hermes_api_server_unavailable", unavailableMessage());
+  }
+  const start = await startHermesGatewayOnce(options.paths ?? resolveRuntimePaths());
+  const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_START_TIMEOUT_MS);
+  while (Date.now() < deadline) {
+    if (await isHermesApiHealthy(configResult.apiServer, fetcher)) {
+      return { available: true, configResult, started: true, start };
+    }
+    await delay(400);
+  }
+  throw new LinkHttpError(
+    503,
+    "hermes_api_server_unavailable",
+    `${unavailableMessage()} Link tried to start it with \`${resolveHermesBin()} gateway run --replace\`, but it did not become ready. Gateway log: ${start.logPath}`
+  );
+}
+async function readHermesVersion() {
+  const { stdout } = await execHermesVersion();
+  const raw = stdout.trim();
+  const version = parseHermesVersion(raw);
+  return {
+    raw,
+    version,
+    supportsApiServer: version ? compareSemver(version, MIN_API_SERVER_VERSION) >= 0 : null
+  };
+}
+async function execHermesVersion() {
+  try {
+    return await execFileAsync2(resolveHermesBin(), ["version"], {
+      timeout: 5e3,
+      windowsHide: true
+    });
+  } catch {
+    return await execFileAsync2(resolveHermesBin(), ["--version"], {
+      timeout: 5e3,
+      windowsHide: true
+    });
+  }
+}
+function assertHermesRunsApiSupported(version, status) {
+  if (status !== 404) {
+    return;
+  }
+  const versionText = version?.version ? `\u5F53\u524D\u68C0\u6D4B\u5230 Hermes Agent ${version.version}\u3002` : "";
+  throw new LinkHttpError(
+    502,
+    "hermes_runs_api_unsupported",
+    `${versionText}\u5F53\u524D Hermes Agent API Server \u4E0D\u652F\u6301 HermesPilot \u9700\u8981\u7684 /v1/runs \u63A5\u53E3\uFF0C\u8BF7\u5148\u8FD0\u884C \`hermes update\` \u5347\u7EA7 Hermes Agent\u3002`
+  );
+}
+async function startHermesGatewayOnce(paths) {
+  if (!gatewayStartInFlight) {
+    gatewayStartInFlight = startHermesGateway(paths).finally(() => {
+      gatewayStartInFlight = null;
+    });
+  }
+  return await gatewayStartInFlight;
+}
+async function startHermesGateway(paths) {
+  const version = await readHermesVersion().catch((error) => {
+    throw new LinkHttpError(
+      503,
+      "hermes_agent_not_available",
+      `\u6CA1\u6709\u627E\u5230\u53EF\u7528\u7684 Hermes Agent CLI\u3002\u8BF7\u5148\u5B89\u88C5 Hermes Agent\uFF0C\u6216\u8BBE\u7F6E HERMES_BIN\u3002${formatErrorSuffix(error)}`
+    );
+  });
+  if (version.supportsApiServer === false) {
+    throw new LinkHttpError(
+      503,
+      "hermes_agent_too_old",
+      `\u5F53\u524D Hermes Agent ${version.version} \u592A\u65E7\uFF0C\u53EF\u80FD\u4E0D\u652F\u6301 Hermes API Server\u3002\u8BF7\u5148\u8FD0\u884C \`hermes update\` \u5347\u7EA7\u3002`
+    );
+  }
+  await mkdir3(paths.logsDir, { recursive: true, mode: 448 });
+  const logPath = path4.join(paths.logsDir, "hermes-gateway.log");
+  const logFile = await open2(logPath, "a", 384);
+  try {
+    const child = spawn(resolveHermesBin(), ["gateway", "run", "--replace"], {
+      detached: true,
+      env: process.env,
+      stdio: ["ignore", logFile.fd, logFile.fd],
+      windowsHide: true
+    });
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (callback) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        callback();
+      };
+      child.once("spawn", () => finish(resolve));
+      child.once("error", (error) => finish(() => reject(error)));
+    });
+    child.unref();
+    return { pid: child.pid ?? null, logPath, version };
+  } finally {
+    await logFile.close().catch(() => void 0);
+  }
+}
+async function isHermesApiHealthy(config, fetcher) {
+  const response = await fetchWithTimeout(`http://127.0.0.1:${config.port}/health`, {
+    method: "GET",
+    headers: authHeaders(config)
+  }, fetcher);
+  return Boolean(response?.ok);
+}
+function fetchWithTimeout(input, init, fetcher) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), HEALTH_TIMEOUT_MS);
+  return fetcher(input, { ...init, signal: controller.signal }).catch(() => null).finally(() => clearTimeout(timer));
+}
+function authHeaders(config) {
+  const headers = new Headers();
+  headers.set("accept", "application/json");
+  if (config.key) {
+    headers.set("x-api-key", config.key);
+    headers.set("authorization", `Bearer ${config.key}`);
+  }
+  return headers;
+}
+function shouldAutoStart(value) {
+  if (value !== void 0) {
+    return value;
+  }
+  const raw = process.env.HERMESLINK_GATEWAY_AUTOSTART?.trim().toLowerCase();
+  return raw !== "0" && raw !== "false" && raw !== "off";
+}
+function unavailableMessage() {
+  return "Hermes API Server \u5F53\u524D\u4E0D\u53EF\u7528\u3002\u8BF7\u786E\u8BA4 Hermes Agent \u5DF2\u5B89\u88C5\uFF0C\u5E76\u53EF\u901A\u8FC7 `hermes gateway run` \u542F\u52A8\uFF1BHermesPilot Link \u9700\u8981 Hermes Agent \u7684\u672C\u673A API Server\u3002";
+}
+function parseHermesVersion(value) {
+  const match = /\bv?(\d+\.\d+\.\d+)\b/u.exec(value);
+  return match?.[1] ?? null;
+}
+function compareSemver(left, right) {
+  const leftParts = left.split(".").map((part) => Number.parseInt(part, 10));
+  const rightParts = right.split(".").map((part) => Number.parseInt(part, 10));
+  for (let index = 0; index < 3; index += 1) {
+    const diff = (leftParts[index] || 0) - (rightParts[index] || 0);
+    if (diff !== 0) {
+      return diff;
+    }
+  }
+  return 0;
+}
+function formatErrorSuffix(error) {
+  if (!(error instanceof Error) || !error.message) {
+    return "";
+  }
+  return ` \u539F\u59CB\u9519\u8BEF\uFF1A${error.message}`;
 }
 
 // src/hermes/api-server.ts
-var fallbackRuns = /* @__PURE__ */ new Map();
 async function listHermesModels(options = {}) {
   const response = await callHermesApi("/v1/models", { method: "GET" }, options);
   if (response.status === 404) {
@@ -234,9 +555,8 @@ async function createHermesRun(input, options = {}) {
     options
   );
   if (response.status === 404 || response.status === 503) {
-    const runId2 = `run_${randomUUID().replaceAll("-", "")}`;
-    fallbackRuns.set(runId2, { input: input.input, createdAt: (/* @__PURE__ */ new Date()).toISOString() });
-    return { run_id: runId2, fallback: true };
+    assertHermesRunsApiSupported(await readHermesVersion().catch(() => null), response.status);
+    throw new LinkHttpError(503, "hermes_api_server_unavailable", "Hermes API Server is unavailable");
   }
   const payload = await readJsonResponse(response);
   const runId = readString(payload, "run_id") ?? readString(payload, "runId") ?? readString(payload, "id");
@@ -246,17 +566,8 @@ async function createHermesRun(input, options = {}) {
   return { run_id: runId, fallback: false };
 }
 async function streamHermesRunEvents(runId, options = {}) {
-  const fallback = fallbackRuns.get(runId);
-  if (fallback) {
-    fallbackRuns.delete(runId);
-    return new Response(createFallbackSseStream(fallback.input), {
-      headers: {
-        "content-type": "text/event-stream; charset=utf-8",
-        "cache-control": "no-store"
-      }
-    });
-  }
   const response = await callHermesApi(`/v1/runs/${encodeURIComponent(runId)}/events`, { method: "GET" }, options);
+  assertHermesRunsApiSupported(await readHermesVersion().catch(() => null), response.status);
   if (!response.ok || !response.body) {
     throw new LinkHttpError(502, "hermes_events_unavailable", "Hermes run event stream is unavailable");
   }
@@ -277,75 +588,68 @@ async function cancelHermesRun(runId, options = {}) {
   if (!response.ok && response.status !== 404) {
     throw new LinkHttpError(502, "hermes_cancel_failed", "Hermes run cancel failed");
   }
-  fallbackRuns.delete(runId);
 }
-async function callHermesApi(path8, init, options) {
-  const config = await readHermesApiServerConfig();
-  if (!config.port || !config.key) {
-    return new Response(null, { status: 503 });
-  }
+async function callHermesApi(path9, init, options) {
+  const availability = await ensureHermesApiServerAvailable({ fetchImpl: options.fetchImpl });
+  const config = availability.configResult.apiServer;
   const fetcher = options.fetchImpl ?? fetch;
+  const request = () => fetchHermesApi(fetcher, config, path9, init);
+  const response = await request();
+  if (response.status !== 401) {
+    return response;
+  }
+  await ensureHermesApiServerAvailable({ fetchImpl: options.fetchImpl, forceRestart: true });
+  return await request();
+}
+async function fetchHermesApi(fetcher, config, path9, init) {
   const headers = new Headers(init.headers);
   headers.set("accept", headers.get("accept") ?? "application/json");
-  headers.set("x-api-key", config.key);
-  headers.set("authorization", `Bearer ${config.key}`);
-  return await fetcher(`http://127.0.0.1:${config.port}${path8}`, {
+  if (config.key) {
+    headers.set("x-api-key", config.key);
+    headers.set("authorization", `Bearer ${config.key}`);
+  }
+  return await fetcher(`http://127.0.0.1:${config.port}${path9}`, {
     ...init,
     headers
-  }).catch(() => new Response(null, { status: 503 }));
+  }).catch(() => {
+    throw new LinkHttpError(503, "hermes_api_server_unavailable", "Hermes API Server is unavailable");
+  });
 }
 async function readJsonResponse(response) {
-  const payload = await response.json().catch(() => null);
+  const raw = await response.text().catch(() => "");
+  const payload = parseJsonObject(raw);
   if (!response.ok || typeof payload !== "object" || payload === null) {
-    throw new LinkHttpError(502, "hermes_response_invalid", "Hermes API Server returned an invalid response");
+    throw new LinkHttpError(
+      502,
+      "hermes_response_invalid",
+      `Hermes API Server returned HTTP ${response.status}: ${readUpstreamMessage(payload, raw)}`
+    );
   }
   return payload;
 }
-function createFallbackSseStream(input) {
-  const encoder = new TextEncoder();
-  return new ReadableStream({
-    start(controller) {
-      const message = `Hermes API Server is not running yet. Link received: ${input}`;
-      controller.enqueue(encoder.encode(`event: message.delta
-data: ${JSON.stringify({ type: "message.delta", delta: message })}
-
-`));
-      controller.enqueue(encoder.encode(`event: run.completed
-data: ${JSON.stringify({ type: "run.completed" })}
-
-`));
-      controller.close();
-    }
-  });
-}
-function readString(payload, key) {
-  const value = payload[key];
-  return typeof value === "string" && value.trim() ? value.trim() : null;
-}
-
-// src/hermes/cli.ts
-import { execFile } from "child_process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile);
-async function deleteHermesSession(sessionId) {
-  if (!sessionId.trim()) {
-    throw new LinkHttpError(400, "hermes_session_id_required", "Hermes session id is required");
+function parseJsonObject(raw) {
+  if (!raw.trim()) {
+    return null;
   }
   try {
-    await execFileAsync(hermesBin(), ["sessions", "delete", sessionId, "--yes"], {
-      timeout: 1e4,
-      windowsHide: true
-    });
-  } catch (error) {
-    throw new LinkHttpError(
-      502,
-      "hermes_session_delete_failed",
-      error instanceof Error ? error.message : "Hermes session delete failed"
-    );
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "object" && parsed !== null ? parsed : null;
+  } catch {
+    return null;
   }
 }
-function hermesBin() {
-  return process.env.HERMES_BIN?.trim() || "hermes";
+function readUpstreamMessage(payload, raw) {
+  const error = typeof payload?.error === "object" && payload.error !== null ? payload.error : null;
+  const message = readString(error ?? {}, "message") ?? readString(payload ?? {}, "message");
+  if (message) {
+    return message;
+  }
+  const body = raw.trim().replace(/\s+/gu, " ").slice(0, 500);
+  return body || "empty response body";
+}
+function readString(payload, key) {
+  const value = payload[key];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 
 // src/conversations/conversation-service.ts
@@ -364,7 +668,7 @@ var ConversationService = class {
   logger;
   emitter = new EventEmitter();
   async listConversations() {
-    await mkdir3(this.paths.conversationsDir, { recursive: true, mode: 448 });
+    await mkdir4(this.paths.conversationsDir, { recursive: true, mode: 448 });
     const entries = await readdir(this.paths.conversationsDir, { withFileTypes: true }).catch((error) => {
       if (isNodeError3(error, "ENOENT")) {
         return [];
@@ -386,9 +690,9 @@ var ConversationService = class {
     return summaries.sort((left, right) => Date.parse(right.updated_at) - Date.parse(left.updated_at));
   }
   async createConversation(input = {}) {
-    await mkdir3(this.paths.conversationsDir, { recursive: true, mode: 448 });
+    await mkdir4(this.paths.conversationsDir, { recursive: true, mode: 448 });
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    const id = `conv_${randomUUID2().replaceAll("-", "")}`;
+    const id = `conv_${randomUUID().replaceAll("-", "")}`;
     const title = input.title?.trim() || "Untitled";
     const manifest = {
       id,
@@ -401,7 +705,7 @@ var ConversationService = class {
       updated_at: now,
       last_event_seq: 0
     };
-    await mkdir3(this.conversationDir(id), { recursive: true, mode: 448 });
+    await mkdir4(this.conversationDir(id), { recursive: true, mode: 448 });
     await this.writeManifest(manifest);
     await this.writeSnapshot(id, emptySnapshot());
     const event = await this.appendEvent(manifest.id, {
@@ -462,7 +766,7 @@ var ConversationService = class {
     }
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const userMessage = {
-      id: `msg_${randomUUID2().replaceAll("-", "")}`,
+      id: `msg_${randomUUID().replaceAll("-", "")}`,
       schema_version: 1,
       conversation_id: manifest.id,
       role: "user",
@@ -481,7 +785,7 @@ var ConversationService = class {
       raw: { format: "hermes-link-user-message", payload: { content, attachments: input.attachments ?? [] } }
     };
     const assistantMessage = {
-      id: `msg_${randomUUID2().replaceAll("-", "")}`,
+      id: `msg_${randomUUID().replaceAll("-", "")}`,
       schema_version: 1,
       conversation_id: manifest.id,
       role: "assistant",
@@ -493,7 +797,7 @@ var ConversationService = class {
       attachments: []
     };
     const run = {
-      id: `run_${randomUUID2().replaceAll("-", "")}`,
+      id: `run_${randomUUID().replaceAll("-", "")}`,
       conversation_id: manifest.id,
       trigger_message_id: userMessage.id,
       assistant_message_id: assistantMessage.id,
@@ -563,9 +867,9 @@ var ConversationService = class {
     if (input.bytes.byteLength > MAX_UPLOADED_BLOB_BYTES) {
       throw new LinkHttpError(413, "blob_too_large", "Blob is too large");
     }
-    const id = `blob_${randomUUID2().replaceAll("-", "")}`;
+    const id = `blob_${randomUUID().replaceAll("-", "")}`;
     const filePath = this.blobPath(id);
-    await mkdir3(path4.dirname(filePath), { recursive: true, mode: 448 });
+    await mkdir4(path5.dirname(filePath), { recursive: true, mode: 448 });
     await writeFile2(filePath, input.bytes, { mode: 384 });
     const manifestPath = `${filePath}.json`;
     const blob = {
@@ -665,7 +969,7 @@ ${attachmentLines.join("\n")}`;
     }
     return this.writeBlob(conversationId, {
       bytes: await readFile3(sourcePath),
-      filename: path4.basename(sourcePath),
+      filename: path5.basename(sourcePath),
       mime: source.mime ?? inferMimeType(sourcePath)
     });
   }
@@ -916,7 +1220,7 @@ ${attachmentLines.join("\n")}`;
       conversation_id: conversationId,
       created_at: now
     };
-    await mkdir3(this.conversationDir(conversationId), { recursive: true, mode: 448 });
+    await mkdir4(this.conversationDir(conversationId), { recursive: true, mode: 448 });
     await appendFile(this.eventsPath(conversationId), `${JSON.stringify(event)}
 `, { mode: 384 });
     await this.writeManifest({
@@ -956,20 +1260,20 @@ ${attachmentLines.join("\n")}`;
   }
   conversationDir(conversationId) {
     assertValidConversationId(conversationId);
-    return path4.join(this.paths.conversationsDir, conversationId);
+    return path5.join(this.paths.conversationsDir, conversationId);
   }
   manifestPath(conversationId) {
-    return path4.join(this.conversationDir(conversationId), "manifest.json");
+    return path5.join(this.conversationDir(conversationId), "manifest.json");
   }
   snapshotPath(conversationId) {
-    return path4.join(this.conversationDir(conversationId), "snapshot.json");
+    return path5.join(this.conversationDir(conversationId), "snapshot.json");
   }
   eventsPath(conversationId) {
-    return path4.join(this.conversationDir(conversationId), "events.ndjson");
+    return path5.join(this.conversationDir(conversationId), "events.ndjson");
   }
   blobPath(blobId) {
     assertValidBlobId(blobId);
-    return path4.join(this.paths.blobsDir, `${blobId}.bin`);
+    return path5.join(this.paths.blobsDir, `${blobId}.bin`);
   }
   liveEventName(conversationId) {
     return `conversation:${conversationId}`;
@@ -996,7 +1300,7 @@ ${attachmentLines.join("\n")}`;
     }
   }
   async listConversationBlobIds(conversationId) {
-    await mkdir3(this.paths.blobsDir, { recursive: true, mode: 448 });
+    await mkdir4(this.paths.blobsDir, { recursive: true, mode: 448 });
     const entries = await readdir(this.paths.blobsDir, { withFileTypes: true }).catch((error) => {
       if (isNodeError3(error, "ENOENT")) {
         return [];
@@ -1013,7 +1317,7 @@ ${attachmentLines.join("\n")}`;
         continue;
       }
       const manifest = await readJsonFile(
-        path4.join(this.paths.blobsDir, entry.name)
+        path5.join(this.paths.blobsDir, entry.name)
       ).catch(() => null);
       if (manifest?.conversation_ids?.includes(conversationId)) {
         blobIds.push(blobId);
@@ -1199,7 +1503,7 @@ function isExplicitMediaPathKey(key) {
   ].includes(key);
 }
 function inferMimeType(filePath) {
-  const extension = path4.extname(filePath).toLowerCase();
+  const extension = path5.extname(filePath).toLowerCase();
   return {
     ".png": "image/png",
     ".jpg": "image/jpeg",
@@ -1261,15 +1565,15 @@ function mediaSourceKey(sourcePath) {
   return createHash("sha256").update(resolveMediaSourcePath(sourcePath)).digest("hex").slice(0, 32);
 }
 function sanitizeFilename(value, fallback) {
-  const base = path4.basename((value ?? "").replace(/[\r\n\t]/gu, " ").trim());
+  const base = path5.basename((value ?? "").replace(/[\r\n\t]/gu, " ").trim());
   const safe = base.replace(/[/:\\]/gu, "_").slice(0, 200).trim();
   return safe || fallback;
 }
 function resolveMediaSourcePath(sourcePath) {
   const trimmed = sourcePath.trim();
-  const expanded = trimmed.startsWith("~/") ? path4.join(process.env.HOME ?? "", trimmed.slice(2)) : trimmed;
-  const resolved = path4.resolve(expanded);
-  if (!path4.isAbsolute(expanded)) {
+  const expanded = trimmed.startsWith("~/") ? path5.join(process.env.HOME ?? "", trimmed.slice(2)) : trimmed;
+  const resolved = path5.resolve(expanded);
+  if (!path5.isAbsolute(expanded)) {
     throw new LinkHttpError(400, "media_source_path_not_absolute", "Hermes output media source must be an absolute path");
   }
   return resolved;
@@ -1296,16 +1600,16 @@ function isNodeError3(error, code) {
 }
 
 // src/hermes/profiles.ts
-import { mkdir as mkdir4, readdir as readdir2, rename as rename2, rm as rm3, stat as stat2 } from "fs/promises";
+import { mkdir as mkdir5, readdir as readdir2, rename as rename2, rm as rm3, stat as stat2 } from "fs/promises";
 import os3 from "os";
-import path5 from "path";
+import path6 from "path";
 var DEFAULT_PROFILE = "default";
 var PROFILE_NAME_PATTERN = /^[a-zA-Z0-9._-]{1,64}$/;
 async function listHermesProfiles(paths = resolveRuntimePaths()) {
   const activeProfile = await getActiveProfile(paths);
   const profiles = /* @__PURE__ */ new Map();
   profiles.set(DEFAULT_PROFILE, profileInfo(DEFAULT_PROFILE, activeProfile));
-  const profilesDir = path5.join(os3.homedir(), ".hermes", "profiles");
+  const profilesDir = path6.join(os3.homedir(), ".hermes", "profiles");
   const entries = await readdir2(profilesDir, { withFileTypes: true }).catch((error) => {
     if (isNodeError4(error, "ENOENT")) {
       return [];
@@ -1352,14 +1656,14 @@ async function createHermesProfile(name) {
   if (await pathExists(profile.path)) {
     throw new Error("profile already exists");
   }
-  await mkdir4(profile.path, { recursive: true, mode: 448 });
+  await mkdir5(profile.path, { recursive: true, mode: 448 });
   await ensureHermesApiServerKey(name, profile.configPath);
   return profile;
 }
 async function useHermesProfile(name, paths = resolveRuntimePaths()) {
   assertProfileName(name);
   const profile = profileInfo(name, name);
-  await mkdir4(profile.path, { recursive: true, mode: 448 });
+  await mkdir5(profile.path, { recursive: true, mode: 448 });
   const current = await readJsonFile(paths.stateFile) ?? {};
   await writeJsonFile(paths.stateFile, { ...current, activeProfile: name });
   return profile;
@@ -1412,8 +1716,8 @@ function isNodeError4(error, code) {
 }
 
 // src/identity/identity.ts
-import { generateKeyPairSync, randomUUID as randomUUID3, sign } from "crypto";
-import { mkdir as mkdir5, chmod } from "fs/promises";
+import { generateKeyPairSync, randomUUID as randomUUID2, sign } from "crypto";
+import { mkdir as mkdir6, chmod } from "fs/promises";
 import { z } from "zod";
 var linkIdentitySchema = z.object({
   install_id: z.string().min(1),
@@ -1435,12 +1739,12 @@ async function ensureIdentity(paths = resolveRuntimePaths()) {
   if (existing) {
     return existing;
   }
-  await mkdir5(paths.homeDir, { recursive: true, mode: 448 });
+  await mkdir6(paths.homeDir, { recursive: true, mode: 448 });
   await chmod(paths.homeDir, 448).catch(() => void 0);
   const { publicKey, privateKey } = generateKeyPairSync("ed25519");
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const identity = {
-    install_id: `install_${randomUUID3().replaceAll("-", "")}`,
+    install_id: `install_${randomUUID2().replaceAll("-", "")}`,
     link_id: null,
     public_key_pem: publicKey.export({ type: "spki", format: "pem" }).toString(),
     private_key_pem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
@@ -1474,11 +1778,11 @@ function getIdentityStatus(identity) {
 }
 
 // src/pairing/pairing.ts
-import path6 from "path";
+import path7 from "path";
 import { rm as rm4 } from "fs/promises";
 
 // src/security/devices.ts
-import { randomBytes as randomBytes2, randomUUID as randomUUID4, timingSafeEqual, createHash as createHash2 } from "crypto";
+import { randomBytes as randomBytes2, randomUUID as randomUUID3, timingSafeEqual, createHash as createHash2 } from "crypto";
 var ACCESS_TOKEN_TTL_MS = 15 * 60 * 1e3;
 var REFRESH_TOKEN_TTL_MS = 90 * 24 * 60 * 60 * 1e3;
 async function createDeviceSession(input, paths = resolveRuntimePaths()) {
@@ -1487,7 +1791,7 @@ async function createDeviceSession(input, paths = resolveRuntimePaths()) {
   const accessToken = randomToken("hpat_");
   const refreshToken = randomToken("hprt_");
   const device = {
-    id: `dev_${randomUUID4().replaceAll("-", "")}`,
+    id: `dev_${randomUUID3().replaceAll("-", "")}`,
     label: input.label,
     platform: input.platform,
     scope: "admin",
@@ -1942,8 +2246,8 @@ async function loadRequiredIdentity(paths) {
   }
   return identity;
 }
-async function postServerJson(serverBaseUrl, path8, body) {
-  const response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path8}`, {
+async function postServerJson(serverBaseUrl, path9, body) {
+  const response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path9}`, {
     method: "POST",
     headers: {
       accept: "application/json",
@@ -1953,8 +2257,8 @@ async function postServerJson(serverBaseUrl, path8, body) {
   });
   return readJsonResponse2(response);
 }
-async function patchServerJson(serverBaseUrl, path8, token, body) {
-  const response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path8}`, {
+async function patchServerJson(serverBaseUrl, path9, token, body) {
+  const response = await fetch(`${serverBaseUrl.replace(/\/+$/u, "")}${path9}`, {
     method: "PATCH",
     headers: {
       accept: "application/json",
@@ -1988,7 +2292,7 @@ function defaultDisplayName() {
   return `Hermes Link ${process.platform}`;
 }
 function pairingClaimPath(sessionId, paths) {
-  return path6.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.claimed.json`);
+  return path7.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.claimed.json`);
 }
 function qrPreferredUrls(routes) {
   return routes.preferredUrls.filter((url) => !url.includes("/api/v1/relay/links/")).slice(0, 1);
@@ -2064,8 +2368,8 @@ function base64UrlToBase64(value) {
 }
 
 // src/runtime/logger.ts
-import { appendFile as appendFile2, mkdir as mkdir6, open as open2, readFile as readFile4, rename as rename3, rm as rm5, stat as stat3 } from "fs/promises";
-import path7 from "path";
+import { appendFile as appendFile2, mkdir as mkdir7, open as open3, readFile as readFile4, rename as rename3, rm as rm5, stat as stat3 } from "fs/promises";
+import path8 from "path";
 var DEFAULT_LOG_FILE = "hermeslink.log";
 var DEFAULT_MAX_FILE_BYTES = 1024 * 1024;
 var DEFAULT_MAX_FILES = 5;
@@ -2113,7 +2417,7 @@ var FileLogger = class {
     return this.queue;
   }
   async appendEntry(entry) {
-    await mkdir6(this.paths.logsDir, { recursive: true, mode: 448 });
+    await mkdir7(this.paths.logsDir, { recursive: true, mode: 448 });
     const line = `${JSON.stringify(entry)}
 `;
     await this.rotateIfNeeded(Buffer.byteLength(line, "utf8"));
@@ -2139,7 +2443,7 @@ function createFileLogger(options = {}) {
   return new FileLogger(options);
 }
 function getLinkLogFile(paths = resolveRuntimePaths(), fileName = DEFAULT_LOG_FILE) {
-  return path7.join(paths.logsDir, fileName);
+  return path8.join(paths.logsDir, fileName);
 }
 async function readRecentLogEntries(options = {}) {
   const paths = options.paths ?? resolveRuntimePaths();
@@ -2241,7 +2545,7 @@ async function readTail(filePath, maxBytes) {
   if (info.size <= maxBytes) {
     return await readFile4(filePath, "utf8").catch(() => null);
   }
-  const handle = await open2(filePath, "r").catch(() => null);
+  const handle = await open3(filePath, "r").catch(() => null);
   if (!handle) {
     return null;
   }
@@ -2780,7 +3084,8 @@ export {
   LINK_COMMAND,
   resolveRuntimePaths,
   loadConfig,
-  ensureHermesApiServerKey,
+  ensureHermesApiServerConfig,
+  ensureHermesApiServerAvailable,
   loadIdentity,
   ensureIdentity,
   getIdentityStatus,
@@ -2791,4 +3096,4 @@ export {
   getLinkLogFile,
   createApp
 };
-//# sourceMappingURL=chunk-VCQJ5DSN.js.map
+//# sourceMappingURL=chunk-L2NM2XMX.js.map