@xyagent/cli 1.0.0 → 1.1.0

package/src-ext/runtime/hermes/envSetup.mjs

@@ -14,13 +14,17 @@
 //   API_SERVER_ENABLED=true
 //   API_SERVER_HOST=127.0.0.1   (仅当未设)
 //   API_SERVER_PORT=8642        (仅当未设)
-// 三行。用户已有自定义 HOST/PORT 不动；只补缺的。
+//   API_SERVER_KEY=<随机强密钥> (缺失或低于 Hermes v0.20 的 16 字符门槛时生成)
+// 四行。用户已有自定义 HOST/PORT 与合格 KEY 不动；只补缺的。
 
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { randomBytes } from "node:crypto";
 
-const REQUIRED_KEYS = ["API_SERVER_ENABLED", "API_SERVER_HOST", "API_SERVER_PORT"];
+// Hermes v0.20+ 要求 API server key 至少 16 字符；默认生成 32 字节 hex。
+const API_SERVER_KEY_MIN_LENGTH = 16;
+const API_SERVER_KEY_BYTES = 32;
 
 const DEFAULTS = {
   API_SERVER_ENABLED: "true",
@@ -76,7 +80,7 @@ function parseEnvFile(content) {
  *     用户自定义的端口 / 监听地址）。
  *
  * 返回 { toAppend, toOverride } —— toAppend 是缺失要追加的 key 列表，
- * toOverride 是已存在但值不对要重写的 key 列表（仅 API_SERVER_ENABLED）。
+ * toOverride 是已存在但值不对要重写的 key 列表（ENABLED 或弱 KEY）。
  */
 function decideEnvPatch(envMap) {
   const toAppend = [];
@@ -92,6 +96,12 @@ function decideEnvPatch(envMap) {
     if (!(k in envMap)) toAppend.push(k);
     // 已设的 host/port 不动，尊重用户自定义（preflight 会自动读取最新值）
   }
+  const apiServerKey = String(envMap.API_SERVER_KEY ?? "").trim();
+  if (!("API_SERVER_KEY" in envMap)) {
+    toAppend.push("API_SERVER_KEY");
+  } else if (apiServerKey.length < API_SERVER_KEY_MIN_LENGTH) {
+    toOverride.push("API_SERVER_KEY");
+  }
   return { toAppend, toOverride };
 }
 
@@ -99,7 +109,7 @@ function decideEnvPatch(envMap) {
  * 用 line-by-line 改写把 toOverride 中的 key 替换成默认值。保留原文件
  * 的注释/空行/格式；只动单行。
  */
-function rewriteEnvOverrides(content, toOverride) {
+function rewriteEnvOverrides(content, toOverride, patchValues) {
   if (toOverride.length === 0) return { content, replaced: [] };
   const overrideSet = new Set(toOverride);
   const replaced = [];
@@ -115,7 +125,7 @@ function rewriteEnvOverrides(content, toOverride) {
     const key = bare.slice(0, eq).trim();
     if (!overrideSet.has(key)) continue;
     // 替换整行；不保留 export / 引号 —— 简单一致
-    lines[i] = `${key}=${DEFAULTS[key]}`;
+    lines[i] = `${key}=${patchValues[key]}`;
     replaced.push(key);
     overrideSet.delete(key);
   }
@@ -129,7 +139,7 @@ function rewriteEnvOverrides(content, toOverride) {
  *   status: "ok" | "patched" | "no_home" | "io_error",
  *   envPath: string,
  *   appended: string[],   // 缺失被追加的 key
- *   overridden: string[], // 已存在但值不对被覆盖的 key (仅 API_SERVER_ENABLED)
+ *   overridden: string[], // 已存在但值不对被覆盖的 key (ENABLED 或弱 KEY)
  *   kept: { key: string, value: string }[], // 保留用户已设的 key/value（HOST/PORT）
  *   error?: string,
  *   warning?: string,
@@ -164,6 +174,10 @@ export function ensureHermesApiServer({ log, home: homeOverride } = {}) {
 
   const envMap = parseEnvFile(content);
   const { toAppend, toOverride } = decideEnvPatch(envMap);
+  const patchValues = { ...DEFAULTS };
+  if (toAppend.includes("API_SERVER_KEY") || toOverride.includes("API_SERVER_KEY")) {
+    patchValues.API_SERVER_KEY = randomBytes(API_SERVER_KEY_BYTES).toString("hex");
+  }
   // 用户已设的 HOST/PORT 列出来，给调用方打印"沿用现有"提示。
   const kept = [];
   for (const k of ["API_SERVER_HOST", "API_SERVER_PORT"]) {
@@ -182,7 +196,7 @@ export function ensureHermesApiServer({ log, home: homeOverride } = {}) {
   let newContent = content;
   let replaced = [];
   if (toOverride.length > 0) {
-    const r = rewriteEnvOverrides(content, toOverride);
+    const r = rewriteEnvOverrides(content, toOverride, patchValues);
     newContent = r.content;
     replaced = r.replaced;
   }
@@ -202,7 +216,7 @@ export function ensureHermesApiServer({ log, home: homeOverride } = {}) {
       "# → bridge 连不上 → App 消息不通。pair 流程强制写齐。",
     );
     for (const k of toAppend) {
-      tail.push(`${k}=${DEFAULTS[k]}`);
+      tail.push(`${k}=${patchValues[k]}`);
     }
     tail.push("");
     newContent += tail.join("\n");

package/src-ext/runtime/hermes/gatewayManager.mjs

@@ -16,10 +16,13 @@ import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 
+import { ensureHermesApiServer } from "./envSetup.mjs";
+
 // gateway 启动后 listen 端口需要时间 —— 热路径 1.5~3s，但冷启动（首次加载
 // skills/记忆/模型路由）实测可 >8s；给到 30s 上限，避免误判超时后回退到默认 profile（错身份）。
 const HEALTH_POLL_INTERVAL_MS = 300;
 const HEALTH_POLL_TIMEOUT_MS = 30000;
+const PROFILE_HEALTH_PROBE_TIMEOUT_MS = 1500;
 // kill 之后等端口完全释放，避免 spawn 时撞 EADDRINUSE。
 const PORT_RELEASE_TIMEOUT_MS = 5000;
 const PORT_RELEASE_INTERVAL_MS = 200;
@@ -129,6 +132,169 @@ export function readProfileEnvValue(hermesHome, key) {
   return "";
 }
 
+/**
+ * 把分配好的端口 upsert 进 `<hermesHome>/.env` 的 `API_SERVER_PORT`（保留其它行）。
+ *
+ * 🔴 为什么必须写（2026-08-16 真机故障）：hermes gateway 只认自己的配置
+ * （进程 env / `<HERMES_HOME>/.env`），**不知道** `gateway-port.json` 的存在。
+ * 分配了 8643 却不告诉 gateway，它就按默认 8642 起 → 与 default profile 的
+ * gateway 撞端口、启动即退 → `waitForHealth(8643)` 永远超时，用户看到
+ * 「profile gateway spawn 后 30000ms 内未通过 /health」。
+ * 写 `.env` 同时让 `resolveProfilePort` 的「.env 优先」路径下次直接命中同一端口，
+ * `ensureHermesApiServer` 的自愈（缺失才补 8642）也不会再把它盖回去。
+ * 写失败不抛：spawn env 里还会带一份 `API_SERVER_PORT`（进程 env 优先级更高），
+ * 单次启动仍然正确，只是下次解析少一层持久化。
+ */
+function upsertProfileEnvPort(hermesHome, port, log) {
+  const envPath = path.join(hermesHome, ".env");
+  const line = `API_SERVER_PORT=${port}`;
+  try {
+    let content = "";
+    try { content = fs.readFileSync(envPath, "utf8"); } catch { /* 没有 .env，全新写 */ }
+    const lines = content.split(/\r?\n/);
+    let replaced = false;
+    for (let i = 0; i < lines.length; i++) {
+      let bare = lines[i].trim();
+      if (!bare || bare.startsWith("#")) continue;
+      if (bare.startsWith("export ")) bare = bare.slice(7).trim();
+      const eq = bare.indexOf("=");
+      if (eq < 0 || bare.slice(0, eq).trim() !== "API_SERVER_PORT") continue;
+      if (lines[i].trim() === line) return; // 已一致，不动文件
+      lines[i] = line;
+      replaced = true;
+      break;
+    }
+    let next;
+    if (replaced) {
+      next = lines.join("\n");
+    } else {
+      const head = content.length > 0 && !content.endsWith("\n") ? `${content}\n` : content;
+      next = `${head}# Added by agentlink（per-profile gateway 端口，与 gateway-port.json 一致）\n${line}\n`;
+    }
+    fs.mkdirSync(hermesHome, { recursive: true });
+    fs.writeFileSync(envPath, next, "utf8");
+  } catch (err) {
+    log?.warn?.("hermes.profile.env_port_write_failed", "写 profile .env 端口失败（spawn env 仍会带端口）", {
+      envPath, port, err: err?.message || String(err),
+    });
+  }
+}
+
+/**
+ * 解析 `<dir>/.env` 为键值表（与 [`readProfileEnvValue`] 同一套行解析规则）。
+ * 文件不存在 / 读失败 → 空表。
+ */
+function readEnvFileMap(dir) {
+  const out = {};
+  try {
+    const raw = fs.readFileSync(path.join(dir, ".env"), "utf8");
+    for (const line of raw.split("\n")) {
+      let t = line.trim();
+      if (!t || t.startsWith("#")) continue;
+      if (t.startsWith("export ")) t = t.slice(7).trim();
+      const eq = t.indexOf("=");
+      if (eq < 0) continue;
+      const key = t.slice(0, eq).trim();
+      let v = t.slice(eq + 1).trim();
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        v = v.slice(1, -1);
+      }
+      if (key && !(key in out)) out[key] = v;
+    }
+  } catch { /* .env 不存在或读失败 */ }
+  return out;
+}
+
+/**
+ * per-profile gateway 从 default profile（`~/.hermes/.env`）**经内存**继承运行凭证
+ * （模型 API key 等）。
+ *
+ * 🔴 为什么需要（2026-08-16 真机第三环故障）：profile home 是 workspace 目录，
+ * 它的 `.env` 只有 agentlink 写入的 API_SERVER_* 四键 —— hermes agent 执行时调
+ * 下游 LLM API 拿不到凭证，把「HTTP 401: Missing Authentication header」当成
+ * 回复正文返回给用户。
+ * 🔴 为什么不落盘：profile home 可能是用户的 git 仓库（powermore 就是），把
+ * OPENAI_API_KEY 之类外部凭证写进项目 `.env` 有被误提交泄漏的风险；
+ * spawn env 只活在进程内存里。
+ *
+ * 继承规则：API_SERVER_* 不继承（per-profile 专属，由调用方显式钉）；
+ * profile 自己 `.env` 已有的键不继承（进程 env 优先于 .env，注入会盖掉用户自定义）。
+ */
+function inheritedDefaultProfileEnv(hermesHome) {
+  const defaultHome = path.join(os.homedir(), ".hermes");
+  if (path.normalize(hermesHome) === path.normalize(defaultHome)) return {};
+  const defaults = readEnvFileMap(defaultHome);
+  const profile = readEnvFileMap(hermesHome);
+  const out = {};
+  for (const [key, value] of Object.entries(defaults)) {
+    if (key.startsWith("API_SERVER_")) continue;
+    if (key in profile) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * spawn 前把 default profile 的模型路由配置带给 per-profile gateway
+ * （2026-08-16 真机第三环故障的固化，方案经端到端验证）：
+ *
+ *   1. **config.yaml 复制**（缺失才复制）：hermes 的模型路由（provider/model/base_url）
+ *      只认 `<HERMES_HOME>/config.yaml`，不支持 env 指定路径（HERMES_CONFIG 只是沙箱
+ *      白名单词条，无消费点）。profile home 缺它时 hermes 回落内置默认模型
+ *      （openrouter），而那家的 key 通常不存在 → agent 把 401 当回复正文返回。
+ *      config.yaml 实测无密钥（模型路由 + agent 行为），落盘 profile home 风险低；
+ *      profile home 是 git 仓库时建议用户将其加进 .gitignore。
+ *   2. **凭证池 env 注入**（纯内存，绝不落盘）：default 的 provider 凭证在
+ *      `~/.hermes/auth.json` 的 credential_pool。auth.json 的 per-provider 全局回落
+ *      （hermes_cli/auth.py `_global_auth_file_path`）只覆盖 provider state，
+ *      **credential_pool 不回落**（实测 profile 进程报 No usable credentials，
+ *      提示设 `<PROVIDER>_API_KEY`）。这里按 hermes 的 env 键名约定
+ *      （provider 大写、`-`→`_`、后缀 `_API_KEY`，minimax-cn→MINIMAX_CN_API_KEY 已实证）
+ *      把池里 api_key 类条目注入 spawn env。键名映射对个别 provider 可能不中 ——
+ *      不中时仅无效果（best-effort），绝不阻塞启动。
+ */
+function defaultProfileModelHandoff(hermesHome, log) {
+  const defaultHome = path.join(os.homedir(), ".hermes");
+  if (path.normalize(hermesHome) === path.normalize(defaultHome)) return {};
+
+  // 1. config.yaml 缺失才复制（已有的绝不覆盖——那是用户的 per-profile 定制）。
+  try {
+    const src = path.join(defaultHome, "config.yaml");
+    const dst = path.join(hermesHome, "config.yaml");
+    if (fs.existsSync(src) && !fs.existsSync(dst)) {
+      fs.copyFileSync(src, dst);
+      log?.info?.("hermes.profile.config_copied", "copied default config.yaml to profile home（git 仓库建议 gitignore）", {
+        hermesHome,
+      });
+    }
+  } catch (err) {
+    log?.warn?.("hermes.profile.config_copy_failed", "config.yaml 复制失败（gateway 将用内置默认模型）", {
+      hermesHome, err: err?.message || String(err),
+    });
+  }
+
+  // 2. credential_pool → <PROVIDER>_API_KEY 内存注入。
+  const env = {};
+  try {
+    const pool = JSON.parse(
+      fs.readFileSync(path.join(defaultHome, "auth.json"), "utf8"),
+    )?.credential_pool;
+    if (pool && typeof pool === "object") {
+      for (const [provider, entries] of Object.entries(pool)) {
+        if (!Array.isArray(entries) || entries.length === 0) continue;
+        const entry = [...entries]
+          .filter((e) => e && typeof e.access_token === "string" && e.access_token)
+          .filter((e) => (e.auth_type ?? "api_key") === "api_key")
+          .sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0))[0];
+        if (!entry) continue;
+        const key = `${provider.toUpperCase().replace(/-/g, "_")}_API_KEY`;
+        env[key] = entry.access_token;
+      }
+    }
+  } catch { /* auth.json 不存在/形状变化：跳过注入，不阻塞启动 */ }
+  return env;
+}
+
 export async function resolveProfilePort(hermesHome) {
   // default profile → 固定 8642
   const defaultHome = path.join(os.homedir(), ".hermes");
@@ -199,7 +365,9 @@ export async function manageProfileGateway(slug, hermesHome, {
     const cached = profileGatewayRegistry.get(slug);
     if (cached && cached.port) {
       const cachedBase = `http://127.0.0.1:${cached.port}`;
-      const probe = await probeHealth(cachedBase, { timeoutMs: 1500 });
+      const probe = await probeHealth(cachedBase, {
+        timeoutMs: PROFILE_HEALTH_PROBE_TIMEOUT_MS,
+      });
       if (probe.ok) {
         cached.lastActiveAt = new Date();
         eLog?.info?.("hermes.profile.gateway.ensure.cached_ok", "profile gateway healthy (cached)", { slug, port: cached.port });
@@ -217,7 +385,9 @@ export async function manageProfileGateway(slug, hermesHome, {
     })();
     if (portFileRead) {
       const savedBase = `http://127.0.0.1:${portFileRead}`;
-      const probe = await probeHealth(savedBase, { timeoutMs: 1500 });
+      const probe = await probeHealth(savedBase, {
+        timeoutMs: PROFILE_HEALTH_PROBE_TIMEOUT_MS,
+      });
       if (probe.ok) {
         eLog?.info?.("hermes.profile.gateway.ensure.portfile_ok", "profile gateway healthy (port file)", { slug, port: portFileRead });
         profileGatewayRegistry.set(slug, {
@@ -239,6 +409,39 @@ export async function manageProfileGateway(slug, hermesHome, {
 
   const baseUrl = `http://127.0.0.1:${port}`;
 
+  // default profile 固定使用 8642 且不会写 gateway-port.json。preflight 已经
+  // 拉起健康 gateway 时，前面的 cache / port-file 两条路径都无法命中；若直接
+  // 进入 stop + spawn，会把刚恢复的 gateway 杀掉，并与 Hermes 自己的 --replace
+  // 清理过程竞争，最终出现“端口曾被占用但现在无人监听”。分配出端口后再做一次
+  // 探活，健康就纳入注册表复用。
+  if (mode === "ensure") {
+    const probe = await probeHealth(baseUrl, {
+      timeoutMs: PROFILE_HEALTH_PROBE_TIMEOUT_MS,
+    });
+    if (probe.ok) {
+      const existingPid = findListeningPid(port) ?? 0;
+      profileGatewayRegistry.set(slug, {
+        port,
+        pid: existingPid,
+        baseUrl,
+        lastActiveAt: new Date(),
+      });
+      eLog?.info?.(
+        "hermes.profile.gateway.ensure.resolved_ok",
+        "profile gateway healthy (resolved port)",
+        { slug, port },
+      );
+      return {
+        ok: true,
+        started: false,
+        pid: existingPid,
+        port,
+        baseUrl,
+        logPath,
+      };
+    }
+  }
+
   // 需要 spawn：先检查并发上限，执行 LRU 驱逐
   await _evictIfNeeded({ eLog });
 
@@ -278,6 +481,28 @@ export async function manageProfileGateway(slug, hermesHome, {
   }
 
   // spawn 新 gateway
+  // 🔴 分配的端口必须同时经两条路交给 gateway（2026-08-16 真机故障，见 upsertProfileEnvPort）：
+  //   1. 进程 env `API_SERVER_PORT`（hermes 的 _getenv 里 os.environ 优先，本次启动立即生效）；
+  //   2. profile `.env` 持久化（下次任何路径拉起 gateway 都一致）。
+  // 少了这一步，gateway 按默认 8642 起、与 default profile 撞端口，健康检查在
+  // 分配端口上永远超时。
+  upsertProfileEnvPort(hermesHome, port, eLog);
+  // 🔴 API_SERVER_KEY 也必须在 spawn 前确定化（2026-08-16 真机第二环故障）：
+  // bridge 发 per-profile 请求时读的是 profile `.env` 的 KEY（handleRequest 的
+  // per-conversation 路由），而 gateway 进程若从 bridge 的 process.env 继承了
+  // default profile 的 KEY，两侧就对不上 —— 表现为 401（profile `.env` 无 KEY 时
+  // bridge 干脆不带鉴权头，「Missing Authentication header」）。
+  // ensureHermesApiServer 幂等：缺 KEY 才生成强随机 key 写入 profile `.env`，
+  // ENABLED/HOST 一并补齐；PORT 已在上一步写好（缺失才补的语义不会碰它）。
+  let profileApiKey = "";
+  try {
+    ensureHermesApiServer({ log: eLog, home: hermesHome });
+    profileApiKey = readProfileEnvValue(hermesHome, "API_SERVER_KEY");
+  } catch (err) {
+    eLog?.warn?.("hermes.profile.env_key_setup_failed", "profile .env key 补齐失败（gateway 仍会尝试启动）", {
+      hermesHome, err: err?.message || String(err),
+    });
+  }
   eLog?.info?.("hermes.profile.gateway.spawn", "spawning profile gateway", { slug, port, hermesHome });
   let spawnResult;
   try {
@@ -285,7 +510,18 @@ export async function manageProfileGateway(slug, hermesHome, {
       binary: effectiveBinary,
       logPath,
       log: eLog,
-      env: { HERMES_HOME: hermesHome },
+      env: {
+        // default profile 的运行凭证（模型 API key 等）经内存继承，
+        // 不落 profile `.env`（见 inheritedDefaultProfileEnv 的红线说明）。
+        ...inheritedDefaultProfileEnv(hermesHome),
+        // 模型路由 config.yaml 复制 + credential_pool 凭证注入（见函数文档）。
+        ...defaultProfileModelHandoff(hermesHome, eLog),
+        HERMES_HOME: hermesHome,
+        API_SERVER_PORT: String(port),
+        // 显式钉住本 profile 的鉴权配置，覆盖从 bridge 进程环境继承来的
+        // default profile 值 —— gateway 与 bridge 必须用同一把 key。
+        ...(profileApiKey ? { API_SERVER_KEY: profileApiKey, API_SERVER_ENABLED: "true" } : {}),
+      },
     });
   } catch (err) {
     return {

package/src-ext/runtime/hermes/handleRequest.mjs

@@ -24,6 +24,7 @@
  */
 
 import { randomBytes } from "node:crypto";
+import { statSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
@@ -113,12 +114,19 @@ const SYSTEM_PROMPT_DEFAULT =
  */
 function _resolveWorkspacePathProfile(workspacePath) {
   if (!workspacePath || typeof workspacePath !== "string") return null;
+  const raw = workspacePath.trim();
+  if (!path.isAbsolute(raw) && raw !== "~" && !raw.startsWith("~/")) return null;
   // expand ~ 前缀
   const expanded = workspacePath.startsWith("~")
     ? path.join(os.homedir(), workspacePath.slice(1))
     : workspacePath;
   const normalized = path.resolve(expanded);
   if (!normalized) return null;
+  try {
+    if (!statSync(normalized).isDirectory()) return null;
+  } catch {
+    return null;
+  }
 
   // align-runtime-default-workspace: root hermesHome（~/.hermes）→ profileName="default"
   const hermesRoot = path.join(os.homedir(), ".hermes");
@@ -209,6 +217,11 @@ export function createHermesHandleRequest({ pre, log, gwId, usage, dispatchHandl
     let effectiveApiKey = pre.apiKey;  // 默认：bridge 启动时固定的 apiKey
 
     const workspaceResolved = workspace_path ? _resolveWorkspacePathProfile(workspace_path) : null;
+    if (workspace_path && !workspaceResolved) {
+      const error = new Error("hermes: requested workspace context is unavailable");
+      error.code = "workspace_context_unavailable";
+      throw error;
+    }
     if (workspaceResolved) {
       const { profileName, profileHome: reqProfileHome } = workspaceResolved;
       let gwResult;

package/src-ext/runtime/hermes/httpBackend.mjs

@@ -145,6 +145,17 @@ export async function* streamChat(messages, opts) {
           try { return JSON.parse(payload); } catch { return null; }
         })();
         if (parsed) {
+          // Hermes 网关在上游鉴权、额度或模型调用失败时仍保持 HTTP 200，
+          // 错误位于最后一个 SSE chunk。不能把它当作空的 completed，否则
+          // Desktop 会永久表现成“没有回复”且用户看不到真实处置原因。
+          const parsedChoice = parsed?.choices?.[0];
+          if (parsed?.error || parsedChoice?.finish_reason === "error") {
+            const message = String(
+              parsed?.error?.message || parsed?.hermes?.error || "Hermes upstream request failed",
+            ).trim();
+            yield { kind: "error", error: message || "Hermes upstream request failed" };
+            return;
+          }
           // OpenAI streaming shape: choices[].delta.content + optional usage on
           // last chunk (with stream_options.include_usage=true).
           //
@@ -156,7 +167,7 @@ export async function* streamChat(messages, opts) {
           // thinking inside delta.content (e.g. Gemini via OpenAI-compat
           // gateway) won't trigger this branch — that's expected, since the
           // upstream has not split reasoning out.
-          const choice = parsed?.choices?.[0];
+          const choice = parsedChoice;
           const reasoningDelta = choice?.delta?.reasoning_content;
           if (typeof reasoningDelta === "string" && reasoningDelta.length > 0) {
             yield { kind: "thinking", text: reasoningDelta };

package/src-ext/runtime/hermes/index.mjs

@@ -109,7 +109,7 @@ export async function runHermesBridge({ options, positional, log }) {
   });
 
   const worker = createRelayWorker({
-    relayUrl: relayBase, gwId, bridgeToken, runtime: "hermes", log: sessLog,
+    relayUrl: relayBase, gwId, bridgeToken, runtime: "hermes", profileName, log: sessLog,
   });
   installAutoTunnel({ relayUrl: relayBase, log: sessLog });
 

package/src-ext/runtime/hermes/preflight.mjs

@@ -320,7 +320,8 @@ export async function hermesPreflightWithHeal({ options = {}, log, hermesHome }
   const envChanged =
     envResult.status === "patched" &&
     (envResult.overridden?.length > 0 ||
-      (envResult.appended || []).includes("API_SERVER_ENABLED"));
+      (envResult.appended || []).some((key) =>
+        key === "API_SERVER_ENABLED" || key === "API_SERVER_KEY"));
   const mode = envChanged ? "restart" : "ensure";
   const effectiveHome = hermesHome || resolveHermesHome();
   const logPath = path.join(effectiveHome, "gateway.log");

package/src-ext/runtime/kimi/index.mjs

@@ -0,0 +1,100 @@
+import { recordBridgedSession } from "../_shared/bridgedSessionLedger.mjs";
+import { runHeadlessCliBridge } from "../_shared/headlessCliBridge.mjs";
+import { probeBinary, runNdjsonProcess } from "../_shared/ndjsonProcess.mjs";
+import { resolveWorkspaceCwd } from "../_shared/resolveWorkspaceCwd.mjs";
+
+export function kimiPreflight({ probe = probeBinary } = {}) {
+  let result = probe("kimi");
+  let binary = "kimi";
+  if (!result.ok) {
+    const legacy = probe("kimi-cli");
+    if (legacy.ok) {
+      result = legacy;
+      binary = "kimi-cli";
+    }
+  }
+  if (!result.ok) result.hint = "请先安装 Kimi Code CLI，并执行 kimi login 完成认证。";
+  return { ...result, binary };
+}
+
+export function translateKimiEvent(event) {
+  if (!event || typeof event !== "object") return null;
+  if (event.role === "assistant") {
+    const chunks = [];
+    if (event.content) {
+      chunks.push({ event: "response.output_text.delta", delta: String(event.content) });
+    }
+    for (const call of Array.isArray(event.tool_calls) ? event.tool_calls : []) {
+      const callId = String(call?.id || "");
+      const name = String(call?.function?.name || "unknown");
+      let input = {};
+      try { input = JSON.parse(call?.function?.arguments || "{}"); } catch {}
+      chunks.push({ event: "response.tool_use.start", call_id: callId, name, input });
+      chunks.push({ event: "response.tool_use.completed", call_id: callId, name, input });
+    }
+    return chunks;
+  }
+  if (event.role === "tool") {
+    const text = typeof event.content === "string" ? event.content : "";
+    return {
+      event: "response.tool_result",
+      call_id: String(event.tool_call_id || ""),
+      output: text ? [{ type: "text", format: "plain", text }] : [],
+      is_error: false,
+    };
+  }
+  return null;
+}
+
+/**
+ * kimi 真实 session id 的前缀（`session.resume_hint` 事件回报的形态）。
+ *
+ * 🔴 2026-08-16 真机故障固化的两条口径（kimi 0.34.0 实测）：
+ *   1. `--print` 参数已不存在（报 `unknown option '--print' (Did you mean --prompt?)`），
+ *      `--prompt` 本身就是「非交互跑一轮并打印」；
+ *   2. `--session <id>` 是**纯 resume** 语义 —— 传一个不存在的 id 直接报
+ *      `Session "..." not found`，不再是旧版的 create-or-resume。所以首轮**不带**
+ *      `--session`（让 CLI 自己建），从输出的 `session.resume_hint` 事件抓真实 id，
+ *      续轮才 resume；老 bridge 存过的 randomUUID 一律不信（没有此前缀）。
+ */
+const KIMI_SESSION_ID_PREFIX = "session_";
+
+export function buildKimiArgs({ input, sessionId }) {
+  const args = ["--prompt", String(input || ""), "--output-format", "stream-json"];
+  if (sessionId) args.push("--session", sessionId);
+  return args;
+}
+
+export function createKimiInvoke({ fallbackWorkspace, preflightResult, log, runProcess = runNdjsonProcess }) {
+  const sessions = new Map();
+  return async ({ thread_id, input, workspace_path, resume_session_id, onChunk, onProcess }) => {
+    const { cwd } = resolveWorkspaceCwd({ workspacePath: workspace_path, fallbackWorkspace, runtime: "kimi", log });
+    // 只信带 kimi 真实前缀的 id（见 KIMI_SESSION_ID_PREFIX 的口径说明）。
+    const saved = sessions.get(thread_id) || resume_session_id;
+    const sessionId =
+      typeof saved === "string" && saved.startsWith(KIMI_SESSION_ID_PREFIX) ? saved : undefined;
+    await runProcess({
+      binary: preflightResult?.binary || "kimi",
+      args: buildKimiArgs({ input, sessionId }),
+      cwd,
+      parseEvent: (event) => {
+        // 首轮 CLI 自建会话后经 resume_hint 回报真实 id —— 记下来供续轮 resume。
+        if (
+          event?.type === "session.resume_hint" &&
+          typeof event.session_id === "string" &&
+          event.session_id.startsWith(KIMI_SESSION_ID_PREFIX)
+        ) {
+          sessions.set(thread_id, event.session_id);
+          recordBridgedSession("kimi", event.session_id); // 打标：桥接产生的 CLI 会话，导入时跳过
+        }
+        return translateKimiEvent(event);
+      },
+      onChunk,
+      onProcess,
+    });
+  };
+}
+
+export async function runKimiBridge({ options, log }) {
+  return runHeadlessCliBridge({ runtime: "kimi", options, log, preflight: kimiPreflight, createInvoke: createKimiInvoke });
+}

package/src-ext/runtime/openclaw/workspaceContext.mjs

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function expandUserPath(value) {
+  const text = String(value || "").trim();
+  if (text === "~") return os.homedir();
+  if (text.startsWith("~/")) return path.join(os.homedir(), text.slice(2));
+  return text;
+}
+
+function configuredAgent(config, agentId) {
+  const entries = Array.isArray(config?.agents?.list) ? config.agents.list.filter(Boolean) : [];
+  const normalized = String(agentId || "main").trim().toLowerCase();
+  return entries.find((entry) => String(entry?.id || "").trim().toLowerCase() === normalized) || null;
+}
+
+function defaultAgentId(config) {
+  const entries = Array.isArray(config?.agents?.list) ? config.agents.list.filter(Boolean) : [];
+  return String(entries.find((entry) => entry?.default)?.id || entries[0]?.id || "main").trim().toLowerCase();
+}
+
+export function resolveConfiguredOpenClawWorkspace(config, agentId) {
+  const normalizedAgentId = String(agentId || "main").trim().toLowerCase() || "main";
+  const configured = configuredAgent(config, normalizedAgentId)?.workspace;
+  if (typeof configured === "string" && configured.trim()) {
+    return path.resolve(expandUserPath(configured));
+  }
+  const fallback = config?.agents?.defaults?.workspace;
+  if (typeof fallback === "string" && fallback.trim()) {
+    const root = path.resolve(expandUserPath(fallback));
+    return normalizedAgentId === defaultAgentId(config) ? root : path.join(root, normalizedAgentId);
+  }
+  if (normalizedAgentId === defaultAgentId(config)) {
+    return path.join(os.homedir(), ".openclaw", "workspace");
+  }
+  return path.join(os.homedir(), ".openclaw", `workspace-${normalizedAgentId}`);
+}
+
+/**
+ * OpenClaw /v1/responses has no request-level cwd field (strict request
+ * schema). Therefore a workspace run is safe only when the selected agent's
+ * configured workspace is exactly the requested directory.
+ */
+export function assertOpenClawWorkspaceContext({ config, agentId, workspacePath }) {
+  const requested = String(workspacePath || "").trim();
+  if (!requested) return;
+  let available = path.isAbsolute(requested);
+  if (available) {
+    try { available = fs.statSync(requested).isDirectory(); } catch { available = false; }
+  }
+  const configured = resolveConfiguredOpenClawWorkspace(config, agentId);
+  if (!available || path.resolve(requested) !== path.resolve(configured)) {
+    const error = new Error("openclaw: requested workspace context is unavailable");
+    error.code = "workspace_context_unavailable";
+    throw error;
+  }
+}