@hermespilot/link 0.5.1 → 0.5.3

package/dist/{chunk-PULX22HX.js → chunk-5JBXQ3VC.js}

@@ -1649,6 +1649,185 @@ async function listHermesModelConfigs(profileName = "default", configPath = reso
     models
   };
 }
+async function listHermesModelConfigCatalog(input) {
+  const targetProfileName = input.targetProfileName?.trim() || null;
+  const targetModels = targetProfileName ? await listHermesModelConfigs(targetProfileName).then((result) => result.models).catch(() => []) : [];
+  const targetKeys = new Set(
+    targetModels.map(
+      (model) => modelConfigKey(model.provider, model.baseUrl, model.id)
+    )
+  );
+  const items = /* @__PURE__ */ new Map();
+  for (const profile of input.profiles) {
+    const profileName = profile.name.trim();
+    if (!profileName) {
+      continue;
+    }
+    const listed = await listHermesModelConfigs(profileName).catch(() => null);
+    if (!listed) {
+      continue;
+    }
+    for (const model of listed.models) {
+      const key = modelConfigKey(model.provider, model.baseUrl, model.id);
+      const existing = items.get(key);
+      if (existing) {
+        if (!existing.sourceProfiles.some(
+          (source) => source.name === profileName
+        )) {
+          existing.sourceProfiles.push({
+            name: profileName,
+            displayName: profile.displayName
+          });
+        }
+        existing.alreadyAdded = existing.alreadyAdded || targetKeys.has(key);
+        existing.isDefault = existing.isDefault || model.isDefault;
+        if (existing.credentialState !== "configured" && model.credentialState === "configured") {
+          existing.credentialState = "configured";
+        }
+        continue;
+      }
+      items.set(key, {
+        id: model.id,
+        provider: model.provider,
+        providerName: model.providerName,
+        baseUrl: model.baseUrl,
+        apiMode: model.apiMode,
+        ...model.contextLength ? { contextLength: model.contextLength } : {},
+        ...model.keyEnv ? { keyEnv: model.keyEnv } : {},
+        credentialState: model.credentialState,
+        isDefault: model.isDefault,
+        ...model.reasoningEffort ? { reasoningEffort: model.reasoningEffort } : {},
+        reasoningSupport: model.reasoningSupport,
+        supportedReasoningEfforts: model.supportedReasoningEfforts,
+        sourceProfiles: [
+          {
+            name: profileName,
+            displayName: profile.displayName
+          }
+        ],
+        alreadyAdded: targetKeys.has(key)
+      });
+    }
+  }
+  return {
+    ok: true,
+    targetProfileName,
+    models: [...items.values()].sort(compareCatalogItems)
+  };
+}
+async function importHermesModelConfig(input, targetProfileName = "default", targetConfigPath = resolveHermesConfigPath(targetProfileName)) {
+  const sourceProfileName = input.sourceProfileName.trim();
+  const modelId = input.modelId.trim();
+  if (!sourceProfileName || !modelId) {
+    throw new Error("sourceProfileName and modelId are required");
+  }
+  const source = await readHermesModelConfigForImport({
+    profileName: sourceProfileName,
+    modelId,
+    provider: input.provider?.trim(),
+    baseUrl: input.baseUrl?.trim(),
+    apiMode: input.apiMode?.trim()
+  });
+  const { document, config, existingRaw } = await readHermesConfigDocument(targetConfigPath);
+  const targetEnv = await readHermesEnvFile(targetProfileName);
+  const customProviders = ensureCustomProvidersList(config);
+  const targetEntryIndex = findCustomProviderIndexByEndpoint(customProviders, {
+    provider: source.model.provider,
+    baseUrl: source.model.baseUrl
+  });
+  const entry = targetEntryIndex >= 0 ? toRecord(customProviders[targetEntryIndex]) : {};
+  const entryHadModels = readEntryModelIds(entry).length > 0;
+  const existingKeyEnv = readString2(entry.key_env) ?? parseEnvReference(readString2(entry.api_key));
+  const existingInlineApiKey = readInlineApiKey(readString2(entry.api_key));
+  const sourceKeyEnv = source.model.keyEnv;
+  const sourceApiKey = sourceKeyEnv ? source.env[sourceKeyEnv]?.trim() : source.inlineApiKey;
+  let keyEnv = existingKeyEnv;
+  if (!keyEnv && !existingInlineApiKey) {
+    keyEnv = sourceKeyEnv ?? (sourceApiKey ? buildApiKeyEnvName(source.model.providerName, source.model.id) : void 0);
+  }
+  if (sourceApiKey && keyEnv && !existingInlineApiKey && (!existingKeyEnv || !targetEnv[keyEnv]?.trim())) {
+    await writeHermesEnvValue(targetProfileName, keyEnv, sourceApiKey);
+  }
+  entry.name = readString2(entry.name) ?? readString2(entry.provider_name) ?? source.model.providerName;
+  entry.provider_key = source.model.provider;
+  entry.base_url = source.model.baseUrl;
+  if (!entryHadModels) {
+    entry.model = source.model.id;
+  }
+  entry.api_mode = source.model.apiMode;
+  addEntryModel(entry, source.model.id);
+  if (source.model.contextLength) {
+    writeEntryModelContextLength(
+      entry,
+      source.model.id,
+      source.model.contextLength
+    );
+  } else if (!entryHadModels) {
+    delete entry.context_length;
+  }
+  if (keyEnv) {
+    entry.key_env = keyEnv;
+    delete entry.api_key;
+  } else {
+    delete entry.key_env;
+    if (!existingInlineApiKey) {
+      delete entry.api_key;
+    }
+  }
+  writeEntryModelReasoningEffort(
+    entry,
+    source.model.id,
+    source.model.reasoningEffort
+  );
+  if (targetEntryIndex >= 0) {
+    customProviders[targetEntryIndex] = entry;
+  } else {
+    customProviders.push(entry);
+  }
+  const modelConfig = ensureRecord(config, "model");
+  const currentDefaultConfig = readModelConfig(modelConfig);
+  const currentDefaultReasoningEffort = readProfileReasoningEffort(config);
+  if (input.setDefault || !currentDefaultConfig.model) {
+    if (input.setDefault && currentDefaultConfig.model && currentDefaultConfig.model !== source.model.id) {
+      retainModelDefaultAsCustomProvider(customProviders, {
+        ...currentDefaultConfig,
+        ...currentDefaultReasoningEffort ? { reasoningEffort: currentDefaultReasoningEffort } : {}
+      });
+    }
+    writeDefaultModelConfig(modelConfig, {
+      id: source.model.id,
+      provider: source.model.provider,
+      baseUrl: source.model.baseUrl,
+      apiMode: source.model.apiMode,
+      contextLength: source.model.contextLength,
+      keyEnv
+    });
+    if (source.model.reasoningEffort) {
+      writeProfileReasoningEffort(config, source.model.reasoningEffort);
+    }
+  }
+  const backupPath = await writeHermesConfigDocument({
+    configPath: targetConfigPath,
+    document,
+    config,
+    existingRaw
+  });
+  const listed = await listHermesModelConfigs(targetProfileName, targetConfigPath);
+  const importedModel = listed.models.find(
+    (model) => model.id === source.model.id && model.provider === source.model.provider && model.baseUrl === source.model.baseUrl
+  ) ?? listed.models.find((model) => model.id === source.model.id);
+  if (!importedModel) {
+    throw new Error("imported model is missing from config");
+  }
+  return {
+    ...listed,
+    model: importedModel,
+    sourceProfileName,
+    backupPath,
+    requiresGatewayReload: true,
+    restartHint: MODEL_CONFIG_RESTART_HINT
+  };
+}
 async function saveHermesModelConfig(input, profileName = "default", configPath = resolveHermesConfigPath(profileName)) {
   const normalized = normalizeModelConfigInput(input);
   const shouldUpdateReasoningEffort = input.reasoningEffort !== void 0;
@@ -2620,6 +2799,14 @@ function findCustomProviderIndex(entries, modelId) {
     (entry) => readEntryModelIds(toRecord(entry)).includes(modelId)
   );
 }
+function findCustomProviderIndexByEndpoint(entries, endpoint) {
+  return entries.findIndex((entry) => {
+    const record = toRecord(entry);
+    const provider = readString2(record.provider_key) ?? readString2(record.provider) ?? "custom";
+    const baseUrl = readString2(record.base_url) ?? readString2(record.url) ?? readString2(record.api) ?? "";
+    return provider.trim().toLowerCase() === endpoint.provider.trim().toLowerCase() && normalizeBaseUrl(baseUrl) === normalizeBaseUrl(endpoint.baseUrl);
+  });
+}
 function updateEntryModels(entry, originalModelId, nextModelId) {
   const models = entry.models;
   if (Array.isArray(models)) {
@@ -2638,6 +2825,39 @@ function updateEntryModels(entry, originalModelId, nextModelId) {
     delete record[originalModelId];
   }
 }
+function addEntryModel(entry, modelId) {
+  const id = modelId.trim();
+  if (!id) {
+    return;
+  }
+  const models = entry.models;
+  if (Array.isArray(models)) {
+    entry.models = Object.fromEntries(
+      Array.from(
+        /* @__PURE__ */ new Set([
+          ...models.filter(
+            (value) => typeof value === "string" && value.trim().length > 0
+          ),
+          id
+        ])
+      ).map((model) => [model, {}])
+    );
+    return;
+  }
+  if (typeof models === "object" && models !== null) {
+    const record = models;
+    record[id] = toRecord(record[id]);
+    return;
+  }
+  if (readString2(entry.model) !== id && readString2(entry.default_model) !== id) {
+    entry.models = Object.fromEntries(
+      Array.from(/* @__PURE__ */ new Set([...readEntryModelIds(entry), id])).map((model) => [
+        model,
+        {}
+      ])
+    );
+  }
+}
 function removeModelFromCustomProvider(entry, modelId) {
   if (readString2(entry.model) === modelId || readString2(entry.default_model) === modelId) {
     delete entry.model;
@@ -2687,6 +2907,27 @@ function readEntryModelContextLength(entry, modelId) {
     modelConfig.context_length ?? modelConfig.contextLength
   );
 }
+function writeEntryModelContextLength(entry, modelId, contextLength) {
+  const models = entry.models;
+  if (typeof models === "object" && models !== null && !Array.isArray(models)) {
+    const modelMap = models;
+    const modelConfig = toRecord(modelMap[modelId]);
+    if (contextLength) {
+      modelConfig.context_length = contextLength;
+    } else {
+      delete modelConfig.context_length;
+      delete modelConfig.contextLength;
+    }
+    modelMap[modelId] = modelConfig;
+    return;
+  }
+  if (contextLength) {
+    entry.context_length = contextLength;
+  } else {
+    delete entry.context_length;
+    delete entry.contextLength;
+  }
+}
 function readEntryModelReasoningEffort(entry, modelId) {
   const models = entry.models;
   if (typeof models === "object" && models !== null && !Array.isArray(models)) {
@@ -2723,6 +2964,80 @@ function writeEntryModelReasoningEffort(entry, modelId, reasoningEffort) {
     delete entry.reasoningEffort;
   }
 }
+async function readHermesModelConfigForImport(input) {
+  const { config } = await readHermesConfigDocument(
+    resolveHermesConfigPath(input.profileName)
+  );
+  const env = await readHermesEnvFile(input.profileName);
+  const models = readManagedModelConfigs(
+    config,
+    env,
+    readModelConfig(config.model).model ?? null,
+    readProfileReasoningEffort(config)
+  );
+  const model = models.find((candidate) => {
+    if (candidate.id !== input.modelId) {
+      return false;
+    }
+    if (input.provider && candidate.provider !== input.provider) {
+      return false;
+    }
+    if (input.baseUrl !== void 0 && normalizeBaseUrl(candidate.baseUrl) !== normalizeBaseUrl(input.baseUrl)) {
+      return false;
+    }
+    if (input.apiMode && candidate.apiMode !== input.apiMode) {
+      return false;
+    }
+    return true;
+  });
+  if (!model) {
+    throw new Error(`model "${input.modelId}" is not configured`);
+  }
+  return {
+    model,
+    env,
+    inlineApiKey: readInlineApiKeyForModel(config, model)
+  };
+}
+function readInlineApiKeyForModel(config, model) {
+  const defaultConfig = readModelConfig(config.model);
+  if (defaultConfig.model === model.id && (defaultConfig.provider ?? "default") === model.provider && normalizeBaseUrl(defaultConfig.baseUrl ?? "") === normalizeBaseUrl(model.baseUrl)) {
+    const key = readInlineApiKey(defaultConfig.apiKey);
+    if (key) {
+      return key;
+    }
+  }
+  const customProviders = Array.isArray(config.custom_providers) ? config.custom_providers : [];
+  for (const rawEntry of customProviders) {
+    const entry = toRecord(rawEntry);
+    const provider = readString2(entry.provider_key) ?? readString2(entry.provider) ?? "custom";
+    const baseUrl = readString2(entry.base_url) ?? readString2(entry.url) ?? readString2(entry.api) ?? "";
+    if (provider === model.provider && normalizeBaseUrl(baseUrl) === normalizeBaseUrl(model.baseUrl) && readEntryModelIds(entry).includes(model.id)) {
+      const key = readInlineApiKey(readString2(entry.api_key));
+      if (key) {
+        return key;
+      }
+    }
+  }
+  return void 0;
+}
+function readInlineApiKey(value) {
+  if (!value || parseEnvReference(value)) {
+    return void 0;
+  }
+  return value.trim() || void 0;
+}
+function compareCatalogItems(left, right) {
+  const provider = left.providerName.localeCompare(right.providerName);
+  if (provider !== 0) {
+    return provider;
+  }
+  const baseUrl = left.baseUrl.localeCompare(right.baseUrl);
+  if (baseUrl !== 0) {
+    return baseUrl;
+  }
+  return left.id.localeCompare(right.id);
+}
 function readCredentialState(entry, env) {
   const apiKey = readString2(entry.api_key);
   const keyEnv = readString2(entry.key_env) ?? parseEnvReference(apiKey);
@@ -2744,10 +3059,13 @@ function readModelCredentialState(model, env) {
   return env[model.keyEnv]?.trim() ? "configured" : "missing";
 }
 function modelConfigKey(provider, baseUrl, modelId) {
-  return [provider, baseUrl.replace(/\/+$/u, ""), modelId].join("\n").toLowerCase();
+  return [provider, normalizeBaseUrl(baseUrl), modelId].join("\n").toLowerCase();
 }
 function modelEndpointKey(baseUrl, modelId) {
-  return [baseUrl.replace(/\/+$/u, ""), modelId].join("\n").toLowerCase();
+  return [normalizeBaseUrl(baseUrl), modelId].join("\n").toLowerCase();
+}
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.trim().replace(/\/+$/u, "");
 }
 function inferApiMode(provider, baseUrl, explicit) {
   const normalizedExplicit = explicit?.trim();
@@ -4184,7 +4502,7 @@ import os2 from "os";
 import path5 from "path";
 
 // src/constants.ts
-var LINK_VERSION = "0.5.1";
+var LINK_VERSION = "0.5.3";
 var LINK_COMMAND = "hermeslink";
 var LINK_DEFAULT_PORT = 52379;
 var LINK_RUNTIME_DIR_NAME = ".hermeslink";
@@ -18228,6 +18546,22 @@ function registerModelConfigRoutes(router, options) {
     ctx.set("cache-control", "no-store");
     ctx.body = await listHermesModelConfigs();
   });
+  router.get("/api/v1/model-configs/catalog", async (ctx) => {
+    await authenticateRequest(ctx, paths);
+    const targetProfileName = readQueryString(ctx.query.target_profile);
+    if (targetProfileName) {
+      await getHermesProfileStatus(targetProfileName, paths);
+    }
+    ctx.set("cache-control", "no-store");
+    const profiles = await listHermesProfiles(paths);
+    ctx.body = await listHermesModelConfigCatalog({
+      targetProfileName,
+      profiles: profiles.map((profile) => ({
+        name: profile.name,
+        displayName: profile.displayName
+      }))
+    });
+  });
   router.post("/api/v1/model-configs", async (ctx) => {
     await authenticateRequest(ctx, paths);
     const body = await readJsonBody(ctx.req);
@@ -18291,6 +18625,23 @@ function registerModelConfigRoutes(router, options) {
       throw toModelConfigHttpError(error);
     }
   });
+  router.post("/api/v1/profiles/:name/model-configs/import", async (ctx) => {
+    await authenticateRequest(ctx, paths);
+    await getHermesProfileStatus(ctx.params.name, paths);
+    const body = await readJsonBody(ctx.req);
+    const input = readModelConfigImportInput(body);
+    await getHermesProfileStatus(input.sourceProfileName, paths);
+    try {
+      const result = await importHermesModelConfig(input, ctx.params.name);
+      ctx.body = shouldReloadGatewayAfterModelConfigChange(body) ? await reloadGatewayAfterProfileModelConfigChange(result, {
+        paths,
+        logger,
+        profileName: ctx.params.name
+      }) : markModelConfigAppliedWithoutGatewayReload(result);
+    } catch (error) {
+      throw toModelConfigHttpError(error);
+    }
+  });
   router.patch("/api/v1/profiles/:name/model-configs/defaults", async (ctx) => {
     await authenticateRequest(ctx, paths);
     await getHermesProfileStatus(ctx.params.name, paths);
@@ -18357,6 +18708,25 @@ function readModelDefaultsInput(body) {
     compressionModelId: readString14(body, "compression_model_id") ?? readString14(body, "compressionModelId") ?? void 0
   };
 }
+function readModelConfigImportInput(body) {
+  const sourceProfileName = readString14(body, "source_profile") ?? readString14(body, "sourceProfile") ?? readString14(body, "source_profile_name") ?? readString14(body, "sourceProfileName");
+  const modelId = readString14(body, "model_id") ?? readString14(body, "modelId") ?? readString14(body, "id");
+  if (!sourceProfileName || !modelId) {
+    throw new LinkHttpError(
+      400,
+      "model_import_invalid",
+      "source_profile and model_id are required"
+    );
+  }
+  return {
+    sourceProfileName,
+    modelId,
+    provider: readString14(body, "provider") ?? readString14(body, "provider_key") ?? readString14(body, "providerKey") ?? void 0,
+    baseUrl: readString14(body, "base_url") ?? readString14(body, "baseUrl") ?? void 0,
+    apiMode: readString14(body, "api_mode") ?? readString14(body, "apiMode") ?? void 0,
+    setDefault: readBoolean3(body.set_default ?? body.setDefault)
+  };
+}
 function shouldReloadGatewayAfterModelConfigChange(body) {
   const explicit = readBoolean3(body.reload_gateway ?? body.reloadGateway) ?? (readBoolean3(body.skip_gateway_reload ?? body.skipGatewayReload) === true ? false : void 0);
   return explicit ?? true;
@@ -19312,6 +19682,7 @@ var CUSTOM_PROVIDER_CARD_ID = "__custom__";
 var CUSTOM_PROVIDER_REGISTRY_FILE = "memory-providers.json";
 var HINDSIGHT_DEFAULT_API_URL = "https://api.hindsight.vectorize.io";
 var HINDSIGHT_DEFAULT_LOCAL_URL = "http://localhost:8888";
+var MEMORY_PROVIDER_TEST_TIMEOUT_MS = 4e3;
 var OPENVIKING_DEFAULT_ENDPOINT = "http://127.0.0.1:1933";
 var RETAINDB_DEFAULT_BASE_URL = "https://api.retaindb.com";
 var HINDSIGHT_LLM_PROVIDERS = [
@@ -19335,25 +19706,25 @@ var MEMORY_PROVIDER_CATALOG = [
   {
     id: "honcho",
     label: "Honcho",
-    description: "AI-native cross-session user modeling provider\uFF1B\u8FD9\u91CC\u53EF\u7F16\u8F91 workspace\u3001peer \u4E0E\u53EC\u56DE\u7B56\u7565\u3002",
+    description: "AI-native cross-session user modeling provider\uFF1B\u8FD9\u91CC\u53EF\u586B\u5199 API Key\uFF0C\u5E76\u7F16\u8F91 workspace\u3001peer \u4E0E\u53EC\u56DE\u7B56\u7565\u3002",
     configurable: true
   },
   {
     id: "openviking",
     label: "OpenViking",
-    description: "\u4E0A\u4E0B\u6587\u6570\u636E\u5E93\u4E0E\u5C42\u7EA7\u77E5\u8BC6\u5E93 provider\uFF1B\u8FD9\u91CC\u53EF\u7F16\u8F91\u975E\u654F\u611F endpoint\u3001account \u4E0E agent \u6807\u8BC6\u3002",
+    description: "\u4E0A\u4E0B\u6587\u6570\u636E\u5E93\u4E0E\u5C42\u7EA7\u77E5\u8BC6\u5E93 provider\uFF1B\u8FD9\u91CC\u53EF\u7F16\u8F91 endpoint\u3001account\u3001agent \u6807\u8BC6\u4E0E\u53EF\u9009 API Key\u3002",
     configurable: true
   },
   {
     id: "mem0",
     label: "Mem0",
-    description: "\u8BED\u4E49\u641C\u7D22\u4E0E\u4E8B\u5B9E\u62BD\u53D6 provider\uFF1B\u8FD9\u91CC\u53EF\u7F16\u8F91 user\u3001agent \u4E0E rerank \u7B56\u7565\u3002",
+    description: "\u8BED\u4E49\u641C\u7D22\u4E0E\u4E8B\u5B9E\u62BD\u53D6 provider\uFF1B\u8FD9\u91CC\u53EF\u586B\u5199 API Key\uFF0C\u5E76\u7F16\u8F91 user\u3001agent \u4E0E rerank \u7B56\u7565\u3002",
     configurable: true
   },
   {
     id: "hindsight",
     label: "Hindsight",
-    description: "\u77E5\u8BC6\u56FE\u8C31\u4E0E\u591A\u7B56\u7565\u68C0\u7D22 provider\uFF1B\u8FD9\u91CC\u53EF\u7F16\u8F91\u975E\u654F\u611F\u8FDE\u63A5\u3001bank \u4E0E\u53EC\u56DE\u7B56\u7565\u3002",
+    description: "\u77E5\u8BC6\u56FE\u8C31\u4E0E\u591A\u7B56\u7565\u68C0\u7D22 provider\uFF1B\u8FD9\u91CC\u53EF\u6309\u8FDE\u63A5\u6A21\u5F0F\u586B\u5199 API Key\u3001LLM Key\u3001URL\u3001bank \u4E0E\u53EC\u56DE\u7B56\u7565\u3002",
     configurable: true
   },
   {
@@ -19365,19 +19736,19 @@ var MEMORY_PROVIDER_CATALOG = [
   {
     id: "retaindb",
     label: "RetainDB",
-    description: "Cloud memory API provider\uFF1B\u8FD9\u91CC\u53EF\u7F16\u8F91\u975E\u654F\u611F endpoint \u4E0E project\u3002",
+    description: "Cloud memory API provider\uFF1B\u8FD9\u91CC\u53EF\u586B\u5199 API Key\uFF0C\u5E76\u7F16\u8F91 endpoint \u4E0E project\u3002",
     configurable: true
   },
   {
     id: "byterover",
     label: "ByteRover",
-    description: "\u57FA\u4E8E brv CLI \u7684\u672C\u5730\u4F18\u5148\u77E5\u8BC6\u6811 provider\uFF1B\u4E91\u540C\u6B65 API key \u9700\u5728\u672C\u673A\u914D\u7F6E\u3002",
-    configurable: false
+    description: "\u57FA\u4E8E brv CLI \u7684\u672C\u5730\u4F18\u5148\u77E5\u8BC6\u6811 provider\uFF1B\u8FD9\u91CC\u53EF\u586B\u5199\u53EF\u9009\u4E91\u540C\u6B65 API Key\uFF0C\u4ECD\u9700\u672C\u673A\u5B89\u88C5 brv CLI\u3002",
+    configurable: true
   },
   {
     id: "supermemory",
     label: "Supermemory",
-    description: "\u8BED\u4E49\u957F\u671F\u8BB0\u5FC6 provider\uFF1B\u8FD9\u91CC\u53EF\u7F16\u8F91\u5BB9\u5668\u3001\u81EA\u52A8\u6355\u83B7\u4E0E\u53EC\u56DE\u7B56\u7565\u3002",
+    description: "\u8BED\u4E49\u957F\u671F\u8BB0\u5FC6 provider\uFF1B\u8FD9\u91CC\u53EF\u586B\u5199 API Key\uFF0C\u5E76\u7F16\u8F91\u5BB9\u5668\u3001\u81EA\u52A8\u6355\u83B7\u4E0E\u53EC\u56DE\u7B56\u7565\u3002",
     configurable: true
   }
 ];
@@ -19464,14 +19835,107 @@ async function saveHermesMemoryProviderSettings(profileName, provider, patch) {
   );
   return readHermesProfileMemory(profileName);
 }
+async function testHermesMemoryProviderSettings(profileName, provider, patch) {
+  const providerId = normalizeConfigurableProvider(provider, patch);
+  if (providerId === "hindsight") {
+    return testHindsightProviderSettings(profileName, patch);
+  }
+  return {
+    ok: false,
+    provider: providerId,
+    message: "\u8FD9\u4E2A memory provider \u6682\u65F6\u8FD8\u6CA1\u6709 App \u5185\u8FDE\u63A5\u6D4B\u8BD5\u3002",
+    checks: []
+  };
+}
 async function setHermesMemoryProvider(profileName, provider) {
   const providerId = normalizeSelectableProvider(provider);
   await assertProviderCanBeActivated(profileName, providerId);
   await patchHermesMemoryProvider(profileName, providerId);
   return readHermesProfileMemory(profileName);
 }
+async function testHindsightProviderSettings(profileName, patch) {
+  const config = await readJsonObject(
+    memoryProviderConfigPath(profileName, "hindsight") ?? ""
+  );
+  const env = await readHermesMemoryEnv(profileName);
+  const mode = normalizeHindsightMode(
+    patch.mode ?? config.mode ?? env.HINDSIGHT_MODE
+  );
+  const apiUrl = readString15(patch.apiUrl) ?? readString15(config.api_url) ?? env.HINDSIGHT_API_URL ?? (mode === "cloud" ? HINDSIGHT_DEFAULT_API_URL : HINDSIGHT_DEFAULT_LOCAL_URL);
+  const bankId = readString15(patch.bankId) ?? readString15(config.bank_id) ?? "hermes";
+  const apiKey = readString15(patch.apiKey) ?? env.HINDSIGHT_API_KEY ?? readString15(config.apiKey) ?? readString15(config.api_key);
+  const baseUrl = normalizeHttpUrl(apiUrl);
+  if (!baseUrl) {
+    return {
+      ok: false,
+      provider: "hindsight",
+      message: "Hindsight API URL \u4E0D\u662F\u6709\u6548\u7684 http/https \u5730\u5740\u3002",
+      checks: [
+        {
+          id: "api_url",
+          label: "API URL",
+          ok: false,
+          detail: "\u8BF7\u8F93\u5165\u6709\u6548\u7684 Hindsight API URL\u3002"
+        }
+      ]
+    };
+  }
+  if (mode === "cloud" && !isConfiguredEnvValue(apiKey)) {
+    return {
+      ok: false,
+      provider: "hindsight",
+      message: "Hindsight Cloud \u9700\u8981\u5148\u586B\u5199 API key \u624D\u80FD\u6D4B\u8BD5\u3002",
+      checks: [
+        {
+          id: "api_key",
+          label: "API key",
+          ok: false,
+          detail: "Cloud \u6A21\u5F0F\u7F3A\u5C11 Hindsight API key\u3002"
+        }
+      ]
+    };
+  }
+  const headers = hindsightRequestHeaders(apiKey);
+  const health = await probeHindsightJson(baseUrl, "/health", headers);
+  const version = await probeHindsightJson(baseUrl, "/version", headers);
+  const bankConfig = await probeHindsightJson(
+    baseUrl,
+    `/v1/default/banks/${encodeURIComponent(bankId)}/config`,
+    headers
+  );
+  const checks = [
+    {
+      id: "health",
+      label: "Hindsight API",
+      ok: health.ok,
+      detail: health.detail
+    },
+    {
+      id: "version",
+      label: "Hindsight version",
+      ok: version.ok,
+      detail: version.detail
+    },
+    {
+      id: "bank",
+      label: `Memory bank "${bankId}"`,
+      ok: bankConfig.ok,
+      detail: bankConfig.detail
+    }
+  ];
+  const ok = checks.every((check) => check.ok);
+  return {
+    ok,
+    provider: "hindsight",
+    message: ok ? "Hindsight \u8FDE\u63A5\u6D4B\u8BD5\u901A\u8FC7\u3002" : "Hindsight \u8FDE\u63A5\u6D4B\u8BD5\u672A\u901A\u8FC7\uFF0C\u8BF7\u68C0\u67E5 API URL\u3001API key \u6216\u670D\u52A1\u72B6\u6001\u3002",
+    checks
+  };
+}
 async function saveProviderSettings(profileName, provider, patch) {
   if (provider === "honcho") {
+    await patchHermesMemoryEnv(profileName, {
+      HONCHO_API_KEY: patch.apiKey
+    });
     await patchJsonProviderConfig(profileName, "honcho.json", {
       baseUrl: patch.baseUrl,
       workspace: patch.workspace,
@@ -19489,6 +19953,9 @@ async function saveProviderSettings(profileName, provider, patch) {
     return;
   }
   if (provider === "mem0") {
+    await patchHermesMemoryEnv(profileName, {
+      MEM0_API_KEY: patch.apiKey
+    });
     await patchJsonProviderConfig(profileName, "mem0.json", {
       user_id: patch.userId,
       agent_id: patch.agentId,
@@ -19499,6 +19966,7 @@ async function saveProviderSettings(profileName, provider, patch) {
   if (provider === "openviking") {
     await patchHermesMemoryEnv(profileName, {
       OPENVIKING_ENDPOINT: patch.endpoint,
+      OPENVIKING_API_KEY: patch.apiKey,
       OPENVIKING_ACCOUNT: patch.account,
       OPENVIKING_USER: patch.user,
       OPENVIKING_AGENT: patch.agent
@@ -19506,6 +19974,9 @@ async function saveProviderSettings(profileName, provider, patch) {
     return;
   }
   if (provider === "supermemory") {
+    await patchHermesMemoryEnv(profileName, {
+      SUPERMEMORY_API_KEY: patch.apiKey
+    });
     await patchJsonProviderConfig(profileName, "supermemory.json", {
       container_tag: patch.containerTag,
       auto_recall: patch.autoRecall,
@@ -19518,6 +19989,10 @@ async function saveProviderSettings(profileName, provider, patch) {
     return;
   }
   if (provider === "hindsight") {
+    await patchHermesMemoryEnv(profileName, {
+      HINDSIGHT_API_KEY: patch.apiKey,
+      HINDSIGHT_LLM_API_KEY: patch.llmApiKey
+    });
     await patchJsonProviderConfig(
       profileName,
       path21.join("hindsight", "config.json"),
@@ -19547,12 +20022,16 @@ async function saveProviderSettings(profileName, provider, patch) {
   }
   if (provider === "retaindb") {
     await patchHermesMemoryEnv(profileName, {
+      RETAINDB_API_KEY: patch.apiKey,
       RETAINDB_BASE_URL: patch.baseUrl,
       RETAINDB_PROJECT: patch.project
     });
     return;
   }
   if (provider === "byterover") {
+    await patchHermesMemoryEnv(profileName, {
+      BRV_API_KEY: patch.apiKey
+    });
     return;
   }
   await patchCustomProviderConfig(profileName, provider, patch);
@@ -19888,7 +20367,7 @@ async function readProviderConfigurationStatus(profileName, provider) {
     );
     return isConfiguredEnvValue(env.HONCHO_API_KEY) || isConfiguredEnvValue(readString15(config2.apiKey)) || isConfiguredEnvValue(readString15(config2.api_key)) || isConfiguredEnvValue(readString15(config2.baseUrl)) ? { configured: true, issue: null } : {
       configured: false,
-      issue: "Honcho \u9700\u8981\u5148\u914D\u7F6E HONCHO_API_KEY\uFF0C\u6216\u5728 honcho.json \u914D\u7F6E self-hosted baseUrl\u3002"
+      issue: "Honcho \u9700\u8981\u5148\u586B\u5199 API Key\uFF0C\u6216\u5728 honcho.json \u914D\u7F6E self-hosted baseUrl\u3002"
     };
   }
   if (provider === "mem0") {
@@ -19897,7 +20376,7 @@ async function readProviderConfigurationStatus(profileName, provider) {
     );
     return isConfiguredEnvValue(env.MEM0_API_KEY) || isConfiguredEnvValue(readString15(config2.api_key)) ? { configured: true, issue: null } : {
       configured: false,
-      issue: "Mem0 \u9700\u8981\u5148\u5728\u672C\u673A Hermes .env \u914D\u7F6E MEM0_API_KEY\u3002"
+      issue: "Mem0 \u9700\u8981\u5148\u5728\u672C\u9875\u586B\u5199 API Key\uFF0CLink \u4F1A\u5199\u5165\u5F53\u524D Profile \u7684 .env\u3002"
     };
   }
   if (provider === "openviking") {
@@ -19909,7 +20388,7 @@ async function readProviderConfigurationStatus(profileName, provider) {
   if (provider === "supermemory") {
     return isConfiguredEnvValue(env.SUPERMEMORY_API_KEY) ? { configured: true, issue: null } : {
       configured: false,
-      issue: "Supermemory \u9700\u8981\u5148\u5728\u672C\u673A Hermes .env \u914D\u7F6E SUPERMEMORY_API_KEY\u3002"
+      issue: "Supermemory \u9700\u8981\u5148\u5728\u672C\u9875\u586B\u5199 API Key\uFF0CLink \u4F1A\u5199\u5165\u5F53\u524D Profile \u7684 .env\u3002"
     };
   }
   if (provider === "holographic") {
@@ -19918,7 +20397,7 @@ async function readProviderConfigurationStatus(profileName, provider) {
   if (provider === "retaindb") {
     return isConfiguredEnvValue(env.RETAINDB_API_KEY) ? { configured: true, issue: null } : {
       configured: false,
-      issue: "RetainDB \u9700\u8981\u5148\u5728\u672C\u673A Hermes .env \u914D\u7F6E RETAINDB_API_KEY\u3002"
+      issue: "RetainDB \u9700\u8981\u5148\u5728\u672C\u9875\u586B\u5199 API Key\uFF0CLink \u4F1A\u5199\u5165\u5F53\u524D Profile \u7684 .env\u3002"
     };
   }
   if (provider === "byterover") {
@@ -19941,7 +20420,7 @@ async function readProviderConfigurationStatus(profileName, provider) {
   if (mode === "cloud") {
     return isConfiguredEnvValue(apiKey) ? { configured: true, issue: null } : {
       configured: false,
-      issue: "Hindsight Cloud \u9700\u8981\u5148\u5728\u672C\u673A Hermes .env \u914D\u7F6E HINDSIGHT_API_KEY\u3002"
+      issue: "Hindsight Cloud \u9700\u8981\u5148\u5728\u672C\u9875\u586B\u5199 API Key\uFF0CLink \u4F1A\u5199\u5165\u5F53\u524D Profile \u7684 .env\u3002"
     };
   }
   if (mode === "local_external") {
@@ -19957,7 +20436,7 @@ async function readProviderConfigurationStatus(profileName, provider) {
     if (!llmModel) {
       return {
         configured: false,
-        issue: "Hindsight local_embedded \u9700\u8981\u5148\u914D\u7F6E LLM \u6A21\u578B\u3002"
+        issue: "Hindsight local_embedded \u9700\u8981\u5148\u586B\u5199 LLM \u6A21\u578B\u3002"
       };
     }
     if (llmProvider === "openai_compatible" && !isConfiguredEnvValue(
@@ -19965,7 +20444,7 @@ async function readProviderConfigurationStatus(profileName, provider) {
     )) {
       return {
         configured: false,
-        issue: "Hindsight openai_compatible \u9700\u8981\u5148\u914D\u7F6E LLM Base URL\u3002"
+        issue: "Hindsight openai_compatible \u9700\u8981\u5148\u586B\u5199 LLM Base URL\u3002"
       };
     }
     if (!["ollama", "lmstudio", "openai_compatible"].includes(llmProvider) && !isConfiguredEnvValue(
@@ -19973,7 +20452,7 @@ async function readProviderConfigurationStatus(profileName, provider) {
     )) {
       return {
         configured: false,
-        issue: "Hindsight local_embedded \u9700\u8981\u5148\u5728\u672C\u673A Hermes .env \u914D\u7F6E HINDSIGHT_LLM_API_KEY\u3002"
+        issue: "Hindsight local_embedded \u9700\u8981\u5148\u586B\u5199 LLM API Key\uFF0CLink \u4F1A\u5199\u5165\u5F53\u524D Profile \u7684 .env\u3002"
       };
     }
     return { configured: true, issue: null };
@@ -20019,8 +20498,15 @@ async function readProviderSettings(profileName, provider) {
     const config = await readJsonObject(
       memoryProviderConfigPath(profileName, provider) ?? ""
     );
+    const env = await readHermesMemoryEnv(profileName);
     return [
       stringSetting("baseUrl", "Base URL", config.baseUrl ?? ""),
+      secretSetting(
+        "apiKey",
+        "API Key",
+        env.HONCHO_API_KEY ?? readString15(config.apiKey) ?? readString15(config.api_key),
+        isConfiguredEnvValue(env.HONCHO_API_KEY) || isConfiguredEnvValue(readString15(config.apiKey)) || isConfiguredEnvValue(readString15(config.api_key))
+      ),
       stringSetting("workspace", "Workspace", config.workspace ?? "hermes"),
       stringSetting("peerName", "\u7528\u6237 Peer", config.peerName ?? ""),
       stringSetting("aiPeer", "AI Peer", config.aiPeer ?? "hermes"),
@@ -20056,7 +20542,14 @@ async function readProviderSettings(profileName, provider) {
     const config = await readJsonObject(
       memoryProviderConfigPath(profileName, provider) ?? ""
     );
+    const env = await readHermesMemoryEnv(profileName);
     return [
+      secretSetting(
+        "apiKey",
+        "API Key",
+        env.MEM0_API_KEY ?? readString15(config.apiKey) ?? readString15(config.api_key),
+        isConfiguredEnvValue(env.MEM0_API_KEY) || isConfiguredEnvValue(readString15(config.apiKey)) || isConfiguredEnvValue(readString15(config.api_key))
+      ),
       stringSetting("userId", "User ID", config.user_id ?? "hermes-user"),
       stringSetting("agentId", "Agent ID", config.agent_id ?? "hermes"),
       booleanSetting("rerank", "\u542F\u7528 rerank", config.rerank ?? true)
@@ -20070,6 +20563,12 @@ async function readProviderSettings(profileName, provider) {
         "Endpoint",
         env.OPENVIKING_ENDPOINT ?? OPENVIKING_DEFAULT_ENDPOINT
       ),
+      secretSetting(
+        "apiKey",
+        "API Key (optional)",
+        env.OPENVIKING_API_KEY,
+        isConfiguredEnvValue(env.OPENVIKING_API_KEY)
+      ),
       stringSetting("account", "Account", env.OPENVIKING_ACCOUNT ?? "default"),
       stringSetting("user", "User", env.OPENVIKING_USER ?? "default"),
       stringSetting("agent", "Agent", env.OPENVIKING_AGENT ?? "hermes")
@@ -20079,7 +20578,14 @@ async function readProviderSettings(profileName, provider) {
     const config = await readJsonObject(
       memoryProviderConfigPath(profileName, provider) ?? ""
     );
+    const env = await readHermesMemoryEnv(profileName);
     return [
+      secretSetting(
+        "apiKey",
+        "API Key",
+        env.SUPERMEMORY_API_KEY,
+        isConfiguredEnvValue(env.SUPERMEMORY_API_KEY)
+      ),
       stringSetting("containerTag", "\u5BB9\u5668\u6807\u7B7E", config.container_tag ?? "hermes"),
       booleanSetting("autoRecall", "\u81EA\u52A8\u56DE\u5FC6", config.auto_recall ?? true),
       booleanSetting("autoCapture", "\u81EA\u52A8\u6355\u83B7", config.auto_capture ?? true),
@@ -20109,6 +20615,7 @@ async function readProviderSettings(profileName, provider) {
     const config = await readJsonObject(
       memoryProviderConfigPath(profileName, provider) ?? ""
     );
+    const env = await readHermesMemoryEnv(profileName);
     const banks = toRecord14(config.banks);
     const hermesBank = toRecord14(banks.hermes);
     const mode = normalizeHindsightMode(config.mode);
@@ -20123,6 +20630,12 @@ async function readProviderSettings(profileName, provider) {
         "API URL",
         config.api_url ?? (mode === "cloud" ? HINDSIGHT_DEFAULT_API_URL : HINDSIGHT_DEFAULT_LOCAL_URL)
       ),
+      secretSetting(
+        "apiKey",
+        "Hindsight API Key",
+        env.HINDSIGHT_API_KEY ?? readString15(config.apiKey) ?? readString15(config.api_key),
+        isConfiguredEnvValue(env.HINDSIGHT_API_KEY) || isConfiguredEnvValue(readString15(config.apiKey)) || isConfiguredEnvValue(readString15(config.api_key))
+      ),
       stringSetting(
         "bankId",
         "Memory Bank",
@@ -20140,6 +20653,12 @@ async function readProviderSettings(profileName, provider) {
         "\u672C\u5730 LLM Base URL",
         config.llm_base_url ?? ""
       ),
+      secretSetting(
+        "llmApiKey",
+        "LLM API Key",
+        env.HINDSIGHT_LLM_API_KEY ?? readString15(config.llmApiKey) ?? readString15(config.llm_api_key),
+        isConfiguredEnvValue(env.HINDSIGHT_LLM_API_KEY) || isConfiguredEnvValue(readString15(config.llmApiKey)) || isConfiguredEnvValue(readString15(config.llm_api_key))
+      ),
       booleanSetting("autoRecall", "\u81EA\u52A8\u56DE\u5FC6", config.auto_recall ?? true),
       booleanSetting("autoRetain", "\u81EA\u52A8\u6C89\u6DC0", config.auto_retain ?? true),
       selectSetting(
@@ -20172,6 +20691,12 @@ async function readProviderSettings(profileName, provider) {
   if (provider === "retaindb") {
     const env = await readHermesMemoryEnv(profileName);
     return [
+      secretSetting(
+        "apiKey",
+        "API Key",
+        env.RETAINDB_API_KEY,
+        isConfiguredEnvValue(env.RETAINDB_API_KEY)
+      ),
       stringSetting(
         "baseUrl",
         "Base URL",
@@ -20181,7 +20706,14 @@ async function readProviderSettings(profileName, provider) {
     ];
   }
   if (provider === "byterover") {
+    const env = await readHermesMemoryEnv(profileName);
     return [
+      secretSetting(
+        "apiKey",
+        "Cloud Sync API Key (optional)",
+        env.BRV_API_KEY,
+        isConfiguredEnvValue(env.BRV_API_KEY)
+      ),
       stringSetting(
         "workingDirectory",
         "\u5DE5\u4F5C\u76EE\u5F55",
@@ -20443,10 +20975,18 @@ async function patchHermesMemoryEnv(profileName, patch) {
 }
 function isMemoryEnvKeyWritable(key) {
   return [
+    "HONCHO_API_KEY",
+    "MEM0_API_KEY",
+    "HINDSIGHT_API_KEY",
+    "HINDSIGHT_LLM_API_KEY",
     "OPENVIKING_ENDPOINT",
+    "OPENVIKING_API_KEY",
     "OPENVIKING_ACCOUNT",
     "OPENVIKING_USER",
     "OPENVIKING_AGENT",
+    "SUPERMEMORY_API_KEY",
+    "BRV_API_KEY",
+    "RETAINDB_API_KEY",
     "RETAINDB_BASE_URL",
     "RETAINDB_PROJECT"
   ].includes(key);
@@ -20455,6 +20995,95 @@ function normalizeHindsightMode(value) {
   const mode = readString15(value) ?? "cloud";
   return mode === "local" ? "local_embedded" : mode;
 }
+function normalizeHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:" ? url : null;
+  } catch {
+    return null;
+  }
+}
+function hindsightRequestHeaders(apiKey) {
+  const headers = { accept: "application/json" };
+  if (isConfiguredEnvValue(apiKey)) {
+    const secret = String(apiKey).trim();
+    headers.authorization = `Bearer ${secret}`;
+    headers["x-api-key"] = secret;
+  }
+  return headers;
+}
+async function probeHindsightJson(baseUrl, pathName, headers) {
+  const url = joinHindsightUrl(baseUrl, pathName);
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(),
+    MEMORY_PROVIDER_TEST_TIMEOUT_MS
+  );
+  try {
+    const response = await fetch(url, {
+      headers,
+      signal: controller.signal
+    });
+    const text = await response.text();
+    const json = parseJsonObject2(text);
+    if (!response.ok) {
+      return {
+        ok: false,
+        detail: `HTTP ${response.status}${readHindsightError(json)}`
+      };
+    }
+    const semanticIssue = hindsightSemanticIssue(pathName, json);
+    if (semanticIssue) {
+      return { ok: false, detail: semanticIssue };
+    }
+    return { ok: true, detail: summarizeHindsightProbe(pathName, json) };
+  } catch (error) {
+    return {
+      ok: false,
+      detail: error instanceof Error && error.name === "AbortError" ? "\u8BF7\u6C42\u8D85\u65F6" : error instanceof Error ? error.message : "\u8BF7\u6C42\u5931\u8D25"
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function joinHindsightUrl(baseUrl, pathName) {
+  const base = new URL(baseUrl.toString());
+  if (!base.pathname.endsWith("/")) {
+    base.pathname = `${base.pathname}/`;
+  }
+  return new URL(pathName.replace(/^\/+/u, ""), base);
+}
+function parseJsonObject2(text) {
+  try {
+    return toRecord14(JSON.parse(text));
+  } catch {
+    return {};
+  }
+}
+function readHindsightError(json) {
+  const detail = readString15(json.detail) ?? readString15(json.error);
+  return detail ? `\uFF1A${detail}` : "";
+}
+function hindsightSemanticIssue(pathName, json) {
+  if (pathName === "/health") {
+    const status = readString15(json.status);
+    return status && ["healthy", "ok"].includes(status.toLowerCase()) ? null : `\u5065\u5EB7\u72B6\u6001\u5F02\u5E38\uFF1A${status ?? "unknown"}`;
+  }
+  return null;
+}
+function summarizeHindsightProbe(pathName, json) {
+  if (pathName === "/health") {
+    const status = readString15(json.status) ?? "ok";
+    const database = readString15(json.database);
+    return database ? `${status}, database ${database}` : status;
+  }
+  if (pathName === "/version") {
+    const version = readString15(json.api_version);
+    return version ? `API ${version}` : "version endpoint reachable";
+  }
+  const bankId = readString15(json.bank_id);
+  return bankId ? `bank ${bankId} reachable` : "bank config reachable";
+}
 async function readActiveMemoryProvider(profileName) {
   const raw = await readFile14(
     resolveHermesConfigPath(profileName),
@@ -20529,6 +21158,16 @@ function stringSetting(key, label, value, editable = true) {
     kind: "string"
   };
 }
+function secretSetting(key, label, value, configured) {
+  return {
+    key,
+    label,
+    value: "",
+    editable: true,
+    kind: "secret",
+    configured: configured || isConfiguredEnvValue(readString15(value))
+  };
+}
 function textSetting(key, label, value, editable = true) {
   return {
     key,
@@ -20752,6 +21391,23 @@ function registerProfileMemoryRoutes(router, options) {
       }
     }
   );
+  router.post(
+    "/api/v1/profiles/:name/memory/providers/:provider/test",
+    async (ctx) => {
+      await authenticateRequest(ctx, paths);
+      const body = await readJsonBody(ctx.req);
+      await getHermesProfileStatus(ctx.params.name, paths);
+      try {
+        ctx.body = await testHermesMemoryProviderSettings(
+          ctx.params.name,
+          ctx.params.provider,
+          readMemorySettingsPatch(body)
+        );
+      } catch (error) {
+        throw toMemoryHttpError(error);
+      }
+    }
+  );
 }
 function readMemoryTarget(body) {
   const raw = readString14(body, "target");
@@ -20818,6 +21474,10 @@ function readMemorySettingsPatch(body) {
   if (apiUrl !== void 0) {
     input.apiUrl = apiUrl;
   }
+  const apiKey = readOptionalSecretString(body, "api_key", "apiKey");
+  if (apiKey !== void 0) {
+    input.apiKey = apiKey;
+  }
   const bankId = readOptionalString(body, "bank_id", "bankId");
   if (bankId !== void 0) {
     input.bankId = bankId;
@@ -20834,6 +21494,14 @@ function readMemorySettingsPatch(body) {
   if (llmBaseUrl !== void 0) {
     input.llmBaseUrl = llmBaseUrl;
   }
+  const llmApiKey = readOptionalSecretString(
+    body,
+    "llm_api_key",
+    "llmApiKey"
+  );
+  if (llmApiKey !== void 0) {
+    input.llmApiKey = llmApiKey;
+  }
   const containerTag = readOptionalString(body, "container_tag", "containerTag");
   if (containerTag !== void 0) {
     input.containerTag = containerTag;
@@ -21034,6 +21702,10 @@ function readOptionalString(body, ...keys) {
   }
   return void 0;
 }
+function readOptionalSecretString(body, ...keys) {
+  const value = readOptionalString(body, ...keys);
+  return value && value.trim().length > 0 ? value : void 0;
+}
 function toMemoryHttpError(error) {
   if (error instanceof HermesMemoryError) {
     return new LinkHttpError(400, error.code, error.message);
@@ -22293,8 +22965,73 @@ import { mkdir as mkdir13, rm as rm8, writeFile as writeFile3 } from "fs/promise
 
 // src/relay/control-client.ts
 import WebSocket from "ws";
-var RELAY_SSE_BATCH_FLUSH_INTERVAL_MS = 50;
-var RELAY_SSE_BATCH_FLUSH_BYTES = 2 * 1024;
+
+// src/relay/stream-policy.ts
+var DEFAULT_RELAY_STREAM_BATCH_POLICY = {
+  flushIntervalMs: 50,
+  flushBytes: 2 * 1024
+};
+var RELAY_STREAM_POLICY_CONSTRAINTS = {
+  flushIntervalMs: {
+    min: 50,
+    max: 1e3
+  },
+  flushBytes: {
+    min: 1024,
+    max: 64 * 1024
+  }
+};
+async function fetchRelayStreamBatchPolicy(serverBaseUrl, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 3e3);
+  timeout.unref?.();
+  try {
+    const response = await fetchImpl(`${serverBaseUrl.replace(/\/+$/u, "")}/api/v1/relay/stream-policy`, {
+      headers: {
+        accept: "application/json"
+      },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const payload = await response.json().catch(() => null);
+    return readRelayStreamBatchPolicy(payload);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function readRelayStreamBatchPolicy(input) {
+  const record = readRecord(input);
+  const body = readRecord(record?.policy) ?? readRecord(record?.stream_batching) ?? record;
+  return normalizeRelayStreamBatchPolicy(body);
+}
+function normalizeRelayStreamBatchPolicy(input) {
+  const record = readRecord(input);
+  if (!record) {
+    return null;
+  }
+  const flushIntervalMs = readInteger4(record.flushIntervalMs ?? record.flush_interval_ms);
+  const flushBytes = readInteger4(record.flushBytes ?? record.flush_bytes);
+  if (flushIntervalMs === null || flushBytes === null || flushIntervalMs < RELAY_STREAM_POLICY_CONSTRAINTS.flushIntervalMs.min || flushIntervalMs > RELAY_STREAM_POLICY_CONSTRAINTS.flushIntervalMs.max || flushBytes < RELAY_STREAM_POLICY_CONSTRAINTS.flushBytes.min || flushBytes > RELAY_STREAM_POLICY_CONSTRAINTS.flushBytes.max) {
+    return null;
+  }
+  return {
+    flushIntervalMs,
+    flushBytes
+  };
+}
+function readRecord(value) {
+  return value && typeof value === "object" ? value : null;
+}
+function readInteger4(value) {
+  return typeof value === "number" && Number.isInteger(value) ? value : null;
+}
+
+// src/relay/control-client.ts
 function connectRelayControl(options) {
   const wsUrl = new URL(`${options.relayBaseUrl.replace(/\/+$/u, "")}/api/v1/relay/link/connect`);
   wsUrl.protocol = wsUrl.protocol === "https:" ? "wss:" : "ws:";
@@ -22309,6 +23046,10 @@ function connectRelayControl(options) {
   let abortControllers = /* @__PURE__ */ new Map();
   let fatalRelayRejection = null;
   let latestNetworkRoutes = null;
+  const streamBatchPolicy = {
+    current: options.initialStreamBatchPolicy ?? DEFAULT_RELAY_STREAM_BATCH_POLICY,
+    onUpdate: options.onStreamBatchPolicy
+  };
   const connect = () => {
     options.onStatus?.({ state: "connecting", attempt: reconnectAttempts });
     fatalRelayRejection = null;
@@ -22329,7 +23070,7 @@ function connectRelayControl(options) {
       if (!socket || typeof raw !== "string" && !Buffer.isBuffer(raw)) {
         return;
       }
-      void handleFrame(socket, String(raw), options.localPort, abortControllers).catch((error) => {
+      void handleFrame(socket, String(raw), options.localPort, abortControllers, streamBatchPolicy).catch((error) => {
         const message = error instanceof Error ? error.message : "Relay request failed";
         socket?.send(JSON.stringify({ type: "http.error", id: "unknown", status: 502, message }));
       });
@@ -22377,6 +23118,10 @@ function connectRelayControl(options) {
         sendNetworkRoutes(socket, options.linkId, routes);
       }
     },
+    updateStreamBatchPolicy(policy) {
+      streamBatchPolicy.current = policy;
+      streamBatchPolicy.onUpdate?.(policy);
+    },
     close() {
       closedByUser = true;
       if (retryTimer) {
@@ -22418,8 +23163,16 @@ function computeBackoffMs(attempt, baseMs, maxMs) {
   const jitter = Math.floor(Math.random() * Math.min(1e3, exponential * 0.2));
   return exponential + jitter;
 }
-async function handleFrame(socket, raw, localPort, abortControllers) {
+async function handleFrame(socket, raw, localPort, abortControllers, streamBatchPolicy) {
   const frame = JSON.parse(raw);
+  if (frame.type === "relay.config.update") {
+    const nextPolicy = readRelayStreamBatchPolicy(frame.payload);
+    if (nextPolicy) {
+      streamBatchPolicy.current = nextPolicy;
+      streamBatchPolicy.onUpdate?.(nextPolicy);
+    }
+    return;
+  }
   if (frame.type === "http.cancel") {
     abortControllers.get(frame.id)?.abort();
     abortControllers.delete(frame.id);
@@ -22442,7 +23195,7 @@ async function handleFrame(socket, raw, localPort, abortControllers) {
     const contentType = response.headers.get("content-type") ?? "";
     if (response.body && contentType.includes("text/event-stream")) {
       socket.send(JSON.stringify({ type: "http.stream.start", id: frame.id, status: response.status, headers }));
-      sseBatcher = createRelayStreamChunkBatcher(socket, frame.id);
+      sseBatcher = createRelayStreamChunkBatcher(socket, frame.id, streamBatchPolicy);
       const reader = response.body.getReader();
       while (true) {
         const next = await reader.read();
@@ -22472,7 +23225,7 @@ async function handleFrame(socket, raw, localPort, abortControllers) {
 function isAbortError2(error) {
   return typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
 }
-function createRelayStreamChunkBatcher(socket, id) {
+function createRelayStreamChunkBatcher(socket, id, streamBatchPolicy) {
   let chunks = [];
   let totalBytes = 0;
   let flushTimer = null;
@@ -22503,7 +23256,7 @@ function createRelayStreamChunkBatcher(socket, id) {
     flushTimer = setTimeout(() => {
       flushTimer = null;
       flush();
-    }, RELAY_SSE_BATCH_FLUSH_INTERVAL_MS);
+    }, streamBatchPolicy.current.flushIntervalMs);
     flushTimer.unref?.();
   };
   return {
@@ -22514,7 +23267,7 @@ function createRelayStreamChunkBatcher(socket, id) {
       const buffer = Buffer.from(chunk);
       chunks.push(buffer);
       totalBytes += buffer.byteLength;
-      if (totalBytes >= RELAY_SSE_BATCH_FLUSH_BYTES) {
+      if (totalBytes >= streamBatchPolicy.current.flushBytes) {
         flush();
         return;
       }
@@ -23282,6 +24035,21 @@ async function startLinkService(options = {}) {
   }
   const conversations = new ConversationService(paths, logger);
   await conversations.rebuildStatisticsIndex();
+  let relay = null;
+  let lanIpMonitor = null;
+  const loadRelayStreamBatchPolicy = async (source) => {
+    const streamBatchPolicy = await fetchRelayStreamBatchPolicy(config.serverBaseUrl);
+    if (!streamBatchPolicy) {
+      return null;
+    }
+    relay?.updateStreamBatchPolicy(streamBatchPolicy);
+    void logger.info("relay_stream_policy_loaded", {
+      source,
+      flushIntervalMs: streamBatchPolicy.flushIntervalMs,
+      flushBytes: streamBatchPolicy.flushBytes
+    });
+    return streamBatchPolicy;
+  };
   let hermesSessionSync = Promise.resolve();
   const triggerHermesSessionSync = () => {
     hermesSessionSync = Promise.resolve().then(() => conversations.syncHermesSessions()).then(() => void 0).catch((error) => {
@@ -23297,6 +24065,7 @@ async function startLinkService(options = {}) {
     conversations,
     onPairingClaimed: async () => {
       triggerHermesSessionSync();
+      void loadRelayStreamBatchPolicy("pairing_claimed");
       await options.onPairingClaimed?.();
     }
   });
@@ -23333,8 +24102,6 @@ async function startLinkService(options = {}) {
     conversations,
     logger
   });
-  let relay = null;
-  let lanIpMonitor = null;
   let hasSeenRelayConnected = false;
   let lastRelayReconnectPublicRouteRefreshAt = 0;
   if (identity?.link_id) {
@@ -23349,6 +24116,12 @@ async function startLinkService(options = {}) {
       maxReconnectAttempts: options.relayMaxReconnectAttempts ?? 5,
       backoffBaseMs: 1e3,
       backoffMaxMs: 3e4,
+      onStreamBatchPolicy: (policy) => {
+        void logger.info("relay_stream_policy_updated", {
+          flushIntervalMs: policy.flushIntervalMs,
+          flushBytes: policy.flushBytes
+        });
+      },
       onStatus: (status) => {
         void logger.info("relay_status", status);
         if (status.state === "connected") {
@@ -23366,6 +24139,7 @@ async function startLinkService(options = {}) {
         }
       }
     });
+    void loadRelayStreamBatchPolicy("service_startup");
     if (options.waitForRelayReady) {
       await Promise.race([
         relayReady,
@@ -23674,7 +24448,11 @@ function wait(ms) {
 
 // src/link/updates.ts
 var SERVER_LINK_CURRENT_RELEASE_PATH = "/api/v1/link/releases/current";
+var SERVER_LINK_INSTALL_SCRIPTS_PATH = "/api/v1/link/install-scripts";
 var LINK_NPM_PACKAGE = "@hermespilot/link";
+var OFFICIAL_INSTALLER_BASE_URL = "https://hs.clawpilot.me/install";
+var OFFICIAL_UNIX_INSTALLER_URL = `${OFFICIAL_INSTALLER_BASE_URL}/install.sh`;
+var OFFICIAL_WINDOWS_INSTALLER_URL = `${OFFICIAL_INSTALLER_BASE_URL}/install.ps1`;
 var UPDATE_LOG_FILE2 = "link-update.log";
 var UPDATE_LOG_MAX_FILES2 = 3;
 var UPDATE_FETCH_TIMEOUT_MS = 5e3;
@@ -23721,6 +24499,13 @@ async function startLinkUpdate(options) {
       "HermesPilot Server has no Link target version."
     );
   }
+  if (!isValidReleaseVersion(targetVersion)) {
+    return writeFailedStartState(
+      options,
+      `HermesPilot Server returned invalid Link target version: ${targetVersion}.`,
+      targetVersion
+    );
+  }
   if (options.targetVersion && options.targetVersion !== targetVersion) {
     return writeFailedStartState(
       options,
@@ -23745,7 +24530,8 @@ async function startLinkUpdate(options) {
     maxFiles: UPDATE_LOG_MAX_FILES2
   });
   const startedAt = now().toISOString();
-  const manualCommand = manualInstallCommand(targetVersion);
+  const installCommand = await buildOfficialInstallCommand(options, targetVersion);
+  const manualCommand = installCommand.displayCommand;
   const started = {
     state: "running",
     job_id: jobId,
@@ -23767,16 +24553,50 @@ async function startLinkUpdate(options) {
   await writer.write(`$ ${manualCommand}
 `);
   await writeUpdateState2(options.paths, started);
-  const child = spawn5(
-    resolveNpmBin(),
-    ["install", "-g", `${LINK_NPM_PACKAGE}@${targetVersion}`],
-    {
-      stdio: ["ignore", "pipe", "pipe"],
-      windowsHide: true,
-      detached: false,
-      shell: false
-    }
-  );
+  if (process.platform === "win32") {
+    await writer.write(
+      "[windows-updater] A detached updater will stop Hermes Link before replacing the npm package, then start it again.\n"
+    );
+    await writer.flush();
+    const child2 = spawnWindowsDetachedUpdater({
+      installCommand,
+      statePath: updateStatePath2(options.paths),
+      logPath: writer.filePath,
+      jobId,
+      targetVersion,
+      startedAt,
+      manualCommand
+    });
+    started.pid = child2.pid ?? null;
+    await writeUpdateState2(options.paths, started);
+    child2.on("error", (error) => {
+      void (async () => {
+        const failed = {
+          ...started,
+          state: "failed",
+          finished_at: now().toISOString(),
+          error: error.message
+        };
+        await writer.write(
+          `
+[failed] Windows detached updater failed to start: ${error.message}
+`
+        );
+        await writeUpdateState2(options.paths, failed);
+        await emitUpdateStatus2(options.paths);
+      })();
+    });
+    await emitUpdateStatus2(options.paths);
+    void options.logger?.info("link_update_started", {
+      job_id: jobId,
+      pid: child2.pid ?? null,
+      target_version: targetVersion,
+      log_path: writer.filePath,
+      strategy: "windows_detached_updater"
+    });
+    return readLinkUpdateStatus(options.paths);
+  }
+  const child = spawnInstallCommand(installCommand);
   started.pid = child.pid ?? null;
   await writeUpdateState2(options.paths, started);
   const appendChunk = async (chunk) => {
@@ -23822,7 +24642,7 @@ async function startLinkUpdate(options) {
           finished_at: now().toISOString(),
           exit_code: code,
           signal,
-          error: succeeded ? null : `npm install exited with code ${code ?? "unknown"}`
+          error: succeeded ? null : `install script exited with code ${code ?? "unknown"}`
         };
         await writer.write(
           `
@@ -23884,18 +24704,23 @@ function scheduleAutomaticRestart(options) {
 }
 async function readLinkUpdateStatus(paths) {
   let state = await readJsonFile(updateStatePath2(paths));
-  if (state?.state === "restart_required" && state.target_version) {
-    if (compareSemver3(LINK_VERSION, state.target_version) >= 0) {
-      state = {
-        ...state,
-        state: "succeeded",
-        finished_at: state.finished_at ?? (/* @__PURE__ */ new Date()).toISOString()
-      };
-      await writeUpdateState2(paths, state);
-    }
+  if ((state?.state === "running" || state?.state === "restart_required") && state.target_version && compareSemver3(LINK_VERSION, state.target_version) >= 0) {
+    state = {
+      ...state,
+      state: "succeeded",
+      finished_at: state.finished_at ?? (/* @__PURE__ */ new Date()).toISOString(),
+      error: null
+    };
+    await writeUpdateState2(paths, state);
   }
   if (state?.state === "running" && !runningUpdate2 && !isRecentRunningState3(state) && !isProcessAlive4(state.pid)) {
-    state = {
+    const reachedTarget = state.target_version && compareSemver3(LINK_VERSION, state.target_version) >= 0;
+    state = reachedTarget ? {
+      ...state,
+      state: "succeeded",
+      finished_at: (/* @__PURE__ */ new Date()).toISOString(),
+      error: null
+    } : {
       ...state,
       state: "failed",
       finished_at: (/* @__PURE__ */ new Date()).toISOString(),
@@ -24029,6 +24854,260 @@ async function fetchCurrentLinkReleaseFromServer(options, fetcher) {
     clearTimeout(timer);
   }
 }
+async function buildOfficialInstallCommand(options, targetVersion) {
+  const installer = await readOfficialInstallerUrls(options).catch((error) => {
+    options.logger?.warn?.(
+      `[link-update] failed to read installer config from server: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return defaultInstallerUrls();
+  });
+  const env = {
+    HERMESLINK_VERSION: targetVersion,
+    HERMESLINK_YES: "1",
+    HERMESLINK_NO_PROFILE_EDIT: "1",
+    HERMESLINK_NO_PATH_PROMPT: "1",
+    HERMESLINK_SKIP_RESTART: "1"
+  };
+  if (process.platform === "win32") {
+    const windowsCommand = `& { $ErrorActionPreference = "Stop"; Invoke-RestMethod ${quotePowerShellString(installer.windowsUrl)} | Invoke-Expression }`;
+    return {
+      command: windowsCommand,
+      displayCommand: `$env:HERMESLINK_VERSION="${targetVersion}"; $env:HERMESLINK_YES="1"; $env:HERMESLINK_NO_PATH_PROMPT="1"; $env:HERMESLINK_SKIP_RESTART="1"; ${windowsCommand}; hermeslink restart`,
+      env,
+      source: "official-installer",
+      installerUrl: installer.windowsUrl
+    };
+  }
+  const unixCommand = buildUnixInstallCommand(installer.unixUrl);
+  return {
+    command: unixCommand,
+    displayCommand: `HERMESLINK_VERSION=${targetVersion} HERMESLINK_YES=1 HERMESLINK_NO_PROFILE_EDIT=1 HERMESLINK_NO_PATH_PROMPT=1 HERMESLINK_SKIP_RESTART=1 sh -c ${quoteShellToken(unixCommand)} && hermeslink restart`,
+    env,
+    source: "official-installer",
+    installerUrl: installer.unixUrl
+  };
+}
+function buildUnixInstallCommand(installerUrl) {
+  const fetchScript = [
+    quoteShellToken(process.execPath),
+    "--input-type=module",
+    "-e",
+    quoteShellToken(
+      "const url = process.env.HERMESLINK_INSTALLER_URL; const response = await fetch(url); if (!response.ok) throw new Error(`HTTP ${response.status}`); process.stdout.write(await response.text());"
+    )
+  ].join(" ");
+  return [
+    "set -e;",
+    'tmp="${TMPDIR:-/tmp}/hermespilot-link-install.$$.sh";',
+    `trap 'rm -f "$tmp"' EXIT;`,
+    "umask 077;",
+    "if command -v curl >/dev/null 2>&1; then",
+    `curl -fsSL ${quoteShellToken(installerUrl)} -o "$tmp";`,
+    "else",
+    `HERMESLINK_INSTALLER_URL=${quoteShellToken(installerUrl)} ${fetchScript} > "$tmp";`,
+    "fi",
+    'bash "$tmp"'
+  ].join(" ");
+}
+async function readOfficialInstallerUrls(options) {
+  const config = await loadConfig(options.paths);
+  const url = new URL(SERVER_LINK_INSTALL_SCRIPTS_PATH, config.serverBaseUrl);
+  const response = await fetchInstallScriptsFromServer(
+    options.fetchImpl ?? fetch,
+    url
+  );
+  if (!response.ok) {
+    throw new Error(`HermesPilot Server returned HTTP ${response.status}`);
+  }
+  const snapshot = await response.json();
+  const commands = snapshot.commands;
+  const unixUrl = readInstallerUrl(commands?.unix, "install.sh");
+  const windowsUrl = readInstallerUrl(commands?.windows, "install.ps1");
+  if (!unixUrl || !windowsUrl) {
+    throw new Error("HermesPilot Server did not return official installer URLs");
+  }
+  return {
+    unixUrl,
+    windowsUrl
+  };
+}
+function defaultInstallerUrls() {
+  return {
+    unixUrl: OFFICIAL_UNIX_INSTALLER_URL,
+    windowsUrl: OFFICIAL_WINDOWS_INSTALLER_URL
+  };
+}
+function readInstallerUrl(value, expectedFileName) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const match = /https:\/\/[^\s'"|]+/u.exec(value);
+  if (!match) {
+    return null;
+  }
+  const url = match[0];
+  if (!isOfficialInstallerUrl(url, expectedFileName)) {
+    return null;
+  }
+  return url;
+}
+function isOfficialInstallerUrl(url, expectedFileName) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:") {
+      return false;
+    }
+    return parsed.hostname === "hs.clawpilot.me" && parsed.pathname === `/install/${expectedFileName}`;
+  } catch {
+    return false;
+  }
+}
+async function fetchInstallScriptsFromServer(fetcher, url) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), UPDATE_FETCH_TIMEOUT_MS);
+  try {
+    return await fetcher(url, {
+      headers: {
+        accept: "application/json",
+        "user-agent": `HermesPilot-Link/${LINK_VERSION}`
+      },
+      signal: controller.signal
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error("HermesPilot Server installer config check timed out");
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function spawnWindowsDetachedUpdater(input) {
+  const child = spawn5(
+    "powershell.exe",
+    [
+      "-NoProfile",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-Command",
+      buildWindowsDetachedUpdaterScript(input)
+    ],
+    {
+      detached: true,
+      stdio: "ignore",
+      cwd: process.env.SystemRoot ?? process.env.TEMP ?? process.cwd(),
+      env: {
+        ...process.env,
+        ...input.installCommand.env
+      },
+      windowsHide: true,
+      shell: false
+    }
+  );
+  child.unref();
+  return child;
+}
+function buildWindowsDetachedUpdaterScript(input) {
+  return [
+    '$ErrorActionPreference = "Stop"',
+    "$Utf8NoBom = New-Object System.Text.UTF8Encoding -ArgumentList $false",
+    `$NodePath = ${quotePowerShellString(process.execPath)}`,
+    `$CliScriptPath = ${quotePowerShellString(currentCliScriptPath())}`,
+    `$InstallerUrl = ${quotePowerShellString(input.installCommand.installerUrl)}`,
+    `$StatePath = ${quotePowerShellString(input.statePath)}`,
+    `$LogPath = ${quotePowerShellString(input.logPath)}`,
+    `$JobId = ${quotePowerShellString(input.jobId)}`,
+    `$TargetVersion = ${quotePowerShellString(input.targetVersion)}`,
+    `$StartedAt = ${quotePowerShellString(input.startedAt)}`,
+    `$ManualCommand = ${quotePowerShellString(input.manualCommand)}`,
+    "$InstallerPath = $null",
+    "function Ensure-ParentDirectory { param([string]$PathValue) $parent = Split-Path -Parent $PathValue; if ($parent) { New-Item -ItemType Directory -Force -Path $parent | Out-Null } }",
+    "function Add-UpdateLog { param([string]$Message) Ensure-ParentDirectory $LogPath; [System.IO.File]::AppendAllText($LogPath, $Message + [Environment]::NewLine, $Utf8NoBom) }",
+    "function Write-UpdateState {",
+    "  param([string]$State, $ExitCode, $ErrorText)",
+    "  Ensure-ParentDirectory $StatePath",
+    "  $finishedAt = $null",
+    '  if ($State -ne "running") { $finishedAt = (Get-Date).ToUniversalTime().ToString("o") }',
+    "  $payload = [ordered]@{",
+    "    state = $State",
+    "    job_id = $JobId",
+    "    pid = $PID",
+    "    target_version = $TargetVersion",
+    "    started_at = $StartedAt",
+    "    finished_at = $finishedAt",
+    "    exit_code = $ExitCode",
+    "    signal = $null",
+    "    error = $ErrorText",
+    "    manual_command = $ManualCommand",
+    "  }",
+    "  $json = $payload | ConvertTo-Json -Compress",
+    "  [System.IO.File]::WriteAllText($StatePath, $json, $Utf8NoBom)",
+    "}",
+    "function Invoke-Step {",
+    "  param([string]$Label, [scriptblock]$Block, [switch]$AllowFailure)",
+    '  Add-UpdateLog ""',
+    '  Add-UpdateLog "=> $Label"',
+    "  & $Block *>> $LogPath",
+    "  $code = if ($null -eq $LASTEXITCODE) { 0 } else { [int]$LASTEXITCODE }",
+    '  if ($code -ne 0 -and -not $AllowFailure) { throw "$Label exited with code $code" }',
+    "  return $code",
+    "}",
+    "try {",
+    '  Write-UpdateState "running" $null $null',
+    "  Start-Sleep -Milliseconds 1500",
+    '  Invoke-Step "Stopping Hermes Link before Windows package replacement" { & $NodePath $CliScriptPath stop } -AllowFailure | Out-Null',
+    '  $InstallerPath = Join-Path ([System.IO.Path]::GetTempPath()) ("hermespilot-link-install-" + [Guid]::NewGuid().ToString("N") + ".ps1")',
+    '  Add-UpdateLog ""',
+    '  Add-UpdateLog "=> Downloading official installer"',
+    '  Invoke-RestMethod -Uri $InstallerUrl -Headers @{ "User-Agent" = "HermesPilot-Link-Updater" } -OutFile $InstallerPath',
+    "  $env:HERMESLINK_VERSION = $TargetVersion",
+    '  $env:HERMESLINK_YES = "1"',
+    '  $env:HERMESLINK_NO_PATH_PROMPT = "1"',
+    '  $env:HERMESLINK_SKIP_RESTART = "1"',
+    '  Invoke-Step "Installing Hermes Link $TargetVersion" { & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $InstallerPath -Version $TargetVersion -NoPathPrompt -SkipRestart } | Out-Null',
+    '  Invoke-Step "Starting Hermes Link after update" { & $NodePath $CliScriptPath start } | Out-Null',
+    '  Add-UpdateLog ""',
+    '  Add-UpdateLog ("=== link update finished " + (Get-Date).ToUniversalTime().ToString("o") + " exit=0 signal=null ===")',
+    '  Write-UpdateState "restart_required" 0 $null',
+    "  exit 0",
+    "} catch {",
+    "  $message = if ($_.Exception) { $_.Exception.Message } else { [string]$_ }",
+    '  Add-UpdateLog ""',
+    '  Add-UpdateLog "[failed] $message"',
+    "  try { & $NodePath $CliScriptPath start *>> $LogPath } catch {}",
+    '  Write-UpdateState "failed" 1 $message',
+    "  exit 1",
+    "} finally {",
+    "  if ($InstallerPath -and (Test-Path -LiteralPath $InstallerPath)) { Remove-Item -LiteralPath $InstallerPath -Force -ErrorAction SilentlyContinue }",
+    "}"
+  ].join("\n");
+}
+function spawnInstallCommand(input) {
+  const env = {
+    ...process.env,
+    ...input.env
+  };
+  if (process.platform === "win32") {
+    return spawn5(
+      "powershell.exe",
+      ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", input.command],
+      {
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+        detached: false,
+        shell: false
+      }
+    );
+  }
+  return spawn5("/bin/sh", ["-lc", input.command], {
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+    detached: false,
+    shell: false
+  });
+}
 async function readLinkReleaseCheckContext(paths) {
   const config = await loadConfig(paths);
   const url = new URL(SERVER_LINK_CURRENT_RELEASE_PATH, config.serverBaseUrl);
@@ -24089,8 +25168,10 @@ async function clearUpdateLogFiles2(paths) {
 function manualInstallCommand(version) {
   return `npm install -g ${LINK_NPM_PACKAGE}@${version}`;
 }
-function resolveNpmBin() {
-  return process.platform === "win32" ? "npm.cmd" : "npm";
+function isValidReleaseVersion(version) {
+  return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(
+    version
+  );
 }
 function compareSemver3(left, right) {
   const leftParts = parseSemver(left);
@@ -24111,6 +25192,15 @@ function parseSemver(value) {
     Number.parseInt(match?.[3] ?? "0", 10)
   ];
 }
+function quoteShellToken(value) {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/u.test(value)) {
+    return value;
+  }
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function quotePowerShellString(value) {
+  return `'${value.replaceAll("'", "''")}'`;
+}
 function isRecentRunningState3(state, now = Date.now()) {
   const startedAt = state.started_at ? Date.parse(state.started_at) : Number.NaN;
   return Number.isFinite(startedAt) && now - startedAt < 1e4;
@@ -25782,6 +26872,7 @@ export {
   readPairingClaim,
   clearPairingClaim,
   createApp,
+  fetchRelayStreamBatchPolicy,
   connectRelayControl,
   reportLinkStatusToServer,
   startLinkService,