@xyagent/cli 0.0.1

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

@@ -0,0 +1,359 @@
+// Hermes 预检。
+//
+// Hermes runtime 走 Nous Research `hermes-agent` 项目（v0.9+）的本地
+// OpenAI-compatible HTTP server（`hermes gateway` 启动后默认监听 8642 端口，
+// 路由有 /v1/chat/completions、/v1/models、/health 等）。localhost 绑定本身
+// 即鉴权，**不需要 API key**。设计目标：**依赖最少**，env / option 都不必配。
+//
+// 决策顺序（首个命中即用）：
+//   1. options.backend === "command" → command backend（显式 opt-in）
+//   2. options.backend === "http" OR `HERMES_BRIDGE_API_BASE_URL` 已设 → http
+//   3. `HERMES_BRIDGE_COMMAND` 已设（且 apiBaseUrl 未显式设）→ command（兼容）
+//   4. 兜底 → http with `http://<API_SERVER_HOST>:<API_SERVER_PORT>/v1`
+//      （从 `~/.hermes/.env` 自动 load 这两个 env；用户没改就 `127.0.0.1:8642`）
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+import { ensureHermesApiServer } from "./envSetup.mjs";
+import { manageHermesGateway, manageProfileGateway, resolveProfilePort, probeHealth } from "./gatewayManager.mjs";
+
+const PREFLIGHT_TIMEOUT_MS = 5000;
+
+// Nous Research `hermes-agent` 的 home dir 与 gateway api-server 默认。
+// 见 ~/.hermes/hermes-agent/gateway/platforms/api_server.py:
+//   DEFAULT_HOST = "127.0.0.1"; DEFAULT_PORT = 8642
+const DEFAULT_API_SERVER_HOST = "127.0.0.1";
+const DEFAULT_API_SERVER_PORT = "8642";
+
+function resolveHermesHome() {
+  const fromEnv = String(process.env.HERMES_HOME || "").trim();
+  if (fromEnv) {
+    return fromEnv.startsWith("~")
+      ? path.join(os.homedir(), fromEnv.slice(1))
+      : fromEnv;
+  }
+  return path.join(os.homedir(), ".hermes");
+}
+
+/**
+ * 按 profileName 解析 per-agent hermes home 目录（profile 隔离入口）。
+ *
+ * 优先级：
+ *   1. HERMES_HOME env 已设（非空）→ 直接返回展开路径（向后兼容）
+ *   2. profileName 非空 → ~/.hermes/profiles/<profileName>（直接用，不截断不转换）
+ *   3. profileName 为空 → 兜底 ~/.hermes
+ *
+ * @param {string} profileName  用户选定的真实 hermes profile 名（profile 目录名）
+ * @returns {string} 绝对路径（不以 / 结尾）
+ */
+export function resolveProfileHome(profileName) {
+  const fromEnv = String(process.env.HERMES_HOME || "").trim();
+  if (fromEnv) {
+    // 展开 ~ 前缀
+    const expanded = fromEnv.startsWith("~")
+      ? path.join(os.homedir(), fromEnv.slice(1))
+      : fromEnv;
+    // path.resolve 去掉尾斜杠，确保返回规范绝对路径
+    return path.resolve(expanded);
+  }
+  if (!profileName) {
+    return path.join(os.homedir(), ".hermes");
+  }
+  return path.join(os.homedir(), ".hermes", "profiles", profileName);
+}
+
+/**
+ * 从 ~/.hermes/.env 把 env 加载到 process.env，不覆盖已有值（process env > .env）。
+ */
+function loadHermesEnvFile() {
+  const envPath = path.join(resolveHermesHome(), ".env");
+  let content;
+  try {
+    content = fs.readFileSync(envPath, "utf8");
+  } catch {
+    return false;
+  }
+  let loaded = 0;
+  for (const rawLine of content.split(/\r?\n/)) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    if (line.startsWith("export ")) line = line.slice(7).trim();
+    const eq = line.indexOf("=");
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim();
+    if (!key || key in process.env) continue;
+    let value = line.slice(eq + 1).trim();
+    if (
+      value.length >= 2 &&
+      value[0] === value[value.length - 1] &&
+      (value[0] === '"' || value[0] === "'")
+    ) {
+      value = value.slice(1, -1);
+    }
+    process.env[key] = value;
+    loaded += 1;
+  }
+  return loaded > 0;
+}
+
+/**
+ * 组装本地 hermes gateway 的 base URL：
+ *   1. HERMES_BRIDGE_API_BASE_URL（agentlink 最高优先级）
+ *   2. API_SERVER_HOST + API_SERVER_PORT（hermes 自家 env，从 ~/.hermes/.env load）
+ *   3. 兜底 127.0.0.1:8642
+ */
+function resolveLocalApiBaseUrl() {
+  const explicit = String(process.env.HERMES_BRIDGE_API_BASE_URL || "").trim();
+  if (explicit) return explicit;
+  const host = (
+    String(process.env.API_SERVER_HOST || "").trim() ||
+    DEFAULT_API_SERVER_HOST
+  );
+  const port = (
+    String(process.env.API_SERVER_PORT || "").trim() ||
+    DEFAULT_API_SERVER_PORT
+  );
+  return `http://${host}:${port}/v1`;
+}
+
+/**
+ * @param {{ options?: any, log?: any }} args
+ * @returns {{ ok: boolean, error?: string, hint?: string,
+ *             backend?: 'http'|'command',
+ *             apiBaseUrl?: string, apiKey?: string, model?: string,
+ *             command?: string[] }}
+ */
+export function hermesPreflight({ options = {}, log } = {}) {
+  const pfLog = log ? log.child({ comp: "child", stage: "preflight" }) : null;
+  // 优先 load ~/.hermes/.env，让 API_SERVER_HOST/PORT 等 hermes 自家 env 进入
+  // process.env（不覆盖已有值）。必须在后续读取之前加载。
+  const envFileLoaded = loadHermesEnvFile();
+  const explicit = String(options.backend || "").toLowerCase();
+  const apiBaseUrl = String(
+    options.apiBaseUrl ||
+      options["api-base-url"] ||
+      "",
+  ).trim();
+  const apiKey = String(
+    options.apiKey ||
+      options["api-key"] ||
+      process.env.HERMES_BRIDGE_API_KEY ||
+      process.env.API_SERVER_KEY ||
+      "",
+  ).trim();
+  const model = String(
+    options.model || process.env.HERMES_BRIDGE_MODEL || "hermes-default",
+  ).trim();
+  const commandRaw = String(
+    options.command ||
+      options["bridge-command"] ||
+      process.env.HERMES_BRIDGE_COMMAND ||
+      "",
+  ).trim();
+
+  // command backend 仅在显式 opt-in（options.backend="command" 或仅设了
+  // HERMES_BRIDGE_COMMAND 而未设 apiBaseUrl）时走。除此之外一律 http，缺省
+  // 兜底本地 hermes gateway。
+  if (
+    explicit === "command" ||
+    (!explicit && commandRaw && !apiBaseUrl)
+  ) {
+    if (!commandRaw) {
+      return {
+        ok: false,
+        error: "command backend requested but no command set",
+        hint: "set --command or HERMES_BRIDGE_COMMAND",
+      };
+    }
+    const argv = parseCommand(commandRaw);
+    if (argv.length === 0) {
+      return { ok: false, error: "empty command", hint: "command parse failed" };
+    }
+    let res;
+    try {
+      res = spawnSync(argv[0], ["--version"], {
+        encoding: "utf8",
+        timeout: PREFLIGHT_TIMEOUT_MS,
+        shell: process.platform === "win32",
+      });
+    } catch {
+      // fall through
+    }
+    if (res?.error?.code === "ENOENT") {
+      return {
+        ok: false,
+        error: `command not found: ${argv[0]}`,
+        hint: "check $PATH or set absolute path in HERMES_BRIDGE_COMMAND",
+      };
+    }
+    pfLog?.info("bridge.preflight.pass", "hermes command backend selected", {
+      command: argv[0],
+      argc: argv.length,
+    });
+    return { ok: true, backend: "command", command: argv, model };
+  }
+
+  // http backend —— option 指定的 apiBaseUrl 优先；否则用 resolveLocalApiBaseUrl()
+  // 走 HERMES_BRIDGE_API_BASE_URL / API_SERVER_HOST+PORT / 默认本地兜底。apiKey
+  // 永远可选；用户改 API_SERVER_PORT 在 ~/.hermes/.env 即可，agentlink 自动跟随。
+  const effectiveBase = apiBaseUrl || resolveLocalApiBaseUrl();
+  pfLog?.info("bridge.preflight.pass", "hermes http backend selected", {
+    api_base_url: effectiveBase,
+    using_resolved_local: !apiBaseUrl,
+    hermes_env_loaded: envFileLoaded,
+    has_api_key: apiKey.length > 0,
+    model,
+  });
+  return { ok: true, backend: "http", apiBaseUrl: effectiveBase, apiKey, model };
+}
+
+// Tokenize a shell-ish command string. Supports double-quoted args. Not a
+// full POSIX shell parser — keeps things predictable and dependency-free.
+function parseCommand(raw) {
+  const out = [];
+  let buf = "";
+  let inQuote = false;
+  for (let i = 0; i < raw.length; i++) {
+    const c = raw[i];
+    if (c === '"') {
+      inQuote = !inQuote;
+      continue;
+    }
+    if (!inQuote && /\s/.test(c)) {
+      if (buf) {
+        out.push(buf);
+        buf = "";
+      }
+      continue;
+    }
+    buf += c;
+  }
+  if (buf) out.push(buf);
+  return out;
+}
+
+/**
+ * 判断 base URL 是否指向本机 —— 只有本机才能自愈，远程 hermes 我们不动用户配置。
+ */
+function isLocalApiBase(baseUrl) {
+  try {
+    const host = new URL(baseUrl).hostname;
+    return host === "127.0.0.1" || host === "localhost" || host === "::1" || host === "0.0.0.0";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 带自愈的 hermesPreflight：在 sync preflight 之后探活 `:8642/health`，挂了就主动
+ *
+ *   1. `ensureHermesApiServer({ log })` 补齐 / 强制 `~/.hermes/.env` 里
+ *      `API_SERVER_ENABLED=true` + HOST/PORT，然后
+ *   2. `manageHermesGateway({ mode: "restart" })` 重启 gateway 让新 env 生效
+ *
+ * 设计动机：pair 流程虽然也会写 env，但用户路径太多（pair/pair-all/agent pair/
+ * 手动 nohup 起 bridge），靠 pair 兜底永远有遗漏；而且 hermes 版本升级会重写
+ * `.env` 模板（见 `~/.hermes/.env.bak-before-*`）抹掉我们的补丁。把自愈下沉到
+ * bridge 启动那一刻，任何路径起的 bridge 都能修。
+ *
+ * 远程 hermes（apiBaseUrl 指向非本机）跳过自愈 —— 用户既然指了远程，他自己负责
+ * 那边的服务状态，我们不去 SSH。
+ *
+ * 测试不变：tests 仍用 sync `hermesPreflight({})`，这里是给 bridge runtime 用的
+ * 额外 wrapper，互不耦合。
+ */
+export async function hermesPreflightWithHeal({ options = {}, log, hermesHome } = {}) {
+  const pre = hermesPreflight({ options, log });
+  if (!pre.ok || pre.backend !== "http") return pre;
+  if (!isLocalApiBase(pre.apiBaseUrl)) return pre;
+
+  const pfLog = log ? log.child({ comp: "child", stage: "preflight-heal" }) : null;
+
+  // per-profile apiBaseUrl：若 hermesHome 传入，用 per-profile 端口（已在 index.mjs 通过
+  // manageProfileGateway 得到）；否则沿用 pre.apiBaseUrl（向后兼容）。
+  const effectiveApiBaseUrl = pre.apiBaseUrl;
+  // apiBaseUrl 形如 "http://127.0.0.1:8642/v1"；probeHealth 自己拼 /health
+  const probeBase = effectiveApiBaseUrl.replace(/\/v1\/?$/, "");
+  const first = await probeHealth(probeBase, { timeoutMs: 2000 });
+  if (first.ok) {
+    pfLog?.info?.("bridge.preflight.health_ok", "hermes gateway alive", { base: probeBase });
+    return pre;
+  }
+
+  pfLog?.warn?.("bridge.preflight.health_miss", "hermes gateway unreachable, self-healing", {
+    base: probeBase,
+    probe_error: first.error || `http_${first.status}`,
+    hermesHome: hermesHome || "(default)",
+  });
+
+  // 自愈：写 per-profile .env（若 hermesHome 传入则写到该目录，否则写全局 ~/.hermes/.env）
+  let envResult;
+  try {
+    envResult = ensureHermesApiServer({ log: pfLog, home: hermesHome || undefined });
+  } catch (err) {
+    return {
+      ok: false,
+      error: `hermes self-heal: env patch threw: ${err?.message || err}`,
+      hint: `check write perm on ${hermesHome ? hermesHome + "/.env" : "~/.hermes/.env"}`,
+    };
+  }
+  if (envResult.status === "no_home") {
+    return {
+      ok: false,
+      error: `${hermesHome || "~/.hermes"} 不存在 —— 先装 nous-research/hermes-agent 并跑一次 \`hermes gateway run\``,
+      hint: "https://github.com/NousResearch/hermes-agent",
+    };
+  }
+  if (envResult.status === "io_error") {
+    return {
+      ok: false,
+      error: `hermes self-heal: ${hermesHome ? hermesHome + "/.env" : "~/.hermes/.env"} 读写失败: ${envResult.error}`,
+      hint: `检查 ${hermesHome ? hermesHome + "/.env" : "~/.hermes/.env"} 文件权限`,
+    };
+  }
+
+  // 决定 manageHermesGateway 的 mode：env 真改了 → restart 强制让 stale 内存换掉
+  const envChanged =
+    envResult.status === "patched" &&
+    (envResult.overridden?.length > 0 ||
+      (envResult.appended || []).includes("API_SERVER_ENABLED"));
+  const mode = envChanged ? "restart" : "ensure";
+  const effectiveHome = hermesHome || resolveHermesHome();
+  const logPath = path.join(effectiveHome, "gateway.log");
+  let mgr;
+  try {
+    mgr = await manageHermesGateway({ baseUrl: probeBase, mode, logPath, log: pfLog });
+  } catch (err) {
+    return {
+      ok: false,
+      error: `hermes self-heal: gateway 启动失败: ${err?.message || err}`,
+      hint: `看日志：tail -50 ${logPath}`,
+    };
+  }
+  if (!mgr.ok) {
+    return {
+      ok: false,
+      error: `hermes self-heal: gateway 不健康 (${mgr.error || "unknown"})`,
+      hint: `看日志：tail -50 ${mgr.logPath || logPath}`,
+    };
+  }
+
+  // 再探一次确认通了；同时重跑 sync preflight 让新 env 进 process.env
+  const after = await probeHealth(probeBase, { timeoutMs: 2000 });
+  if (!after.ok) {
+    return {
+      ok: false,
+      error: `hermes self-heal: gateway 启动了但 /health 仍不通 (${after.error || `http_${after.status}`})`,
+      hint: `看日志：tail -50 ${mgr.logPath || logPath}`,
+    };
+  }
+  pfLog?.info?.("bridge.preflight.heal_ok", "hermes gateway self-healed", {
+    base: probeBase, env_changed: envChanged, mode, hermesHome: effectiveHome,
+  });
+  // 重跑一遍 sync preflight：env 已写入 process.env，pre.apiKey 可能从空变成 API_SERVER_KEY
+  return hermesPreflight({ options, log });
+}

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

@@ -0,0 +1,276 @@
+// Hermes runtime — Responses API (POST /v1/responses) streaming backend.
+//
+// 跟 httpBackend.mjs 并列：那条走 OpenAI 通用的 /v1/chat/completions（兼容
+// LM Studio / Ollama / vLLM 等任意 OpenAI-compatible 后端），本文件走
+// hermes-agent **自家**实现的 /v1/responses（OpenAI Responses API 风格）。
+//
+// 切到 /v1/responses 的唯一动机是：chat/completions 端点上 hermes-agent 不
+// 把 delegate_task 的真实返回值（subagent 实际答案的 JSON）放进 SSE 流；
+// `_handle_chat_completions` 的 `_on_tool_progress` 只过 `tool.started`，
+// `tool.completed`（带 result）整个被丢（api_server.py:751）。Responses API
+// 走 `tool_complete_callback` 把 result 直接 emit 成 `function_call_output`
+// item，bridge 可以拿到子 agent 输出。
+//
+// 协议参考：~/.hermes/hermes-agent/gateway/platforms/api_server.py
+//   _write_sse_responses (line ~994)
+//
+// 关心的 SSE 事件：
+//   response.created                              — 初始 envelope（ignore）
+//   response.output_item.added                    — 新输出项加入
+//     item.type=message    → 文本块容器开启（ignore，靠 delta 累积）
+//     item.type=function_call    → tool 调用开始（status=in_progress）
+//     item.type=function_call_output → tool 调用结果（status=completed/failed）
+//   response.output_item.done with type=function_call
+//                                                 → tool arguments 终态
+//   response.output_text.delta                    — 文本 delta
+//   response.completed                            — 终止
+//   response.failed                               — 终止 + 错误
+//
+// 输出 chunk（兼容 handleRequest defaultOpenclawInvoke 主循环）：
+//   { kind: "delta", text }            — 文本 delta（同 httpBackend）
+//   { kind: "thinking", text }          — reasoning delta（同 httpBackend）
+//   { kind: "tool_call_started", call_id, name, arguments }
+//                                       — function_call item 抵达
+//   { kind: "tool_call_completed", call_id, name, result, is_error }
+//                                       — function_call_output item 抵达，
+//                                         result 是字符串（tool 返回值 JSON
+//                                         /纯文本，由调用方解析）
+//   { kind: "done", fullText, usage }   — 终止
+//   { kind: "error", error }            — 错误
+
+/**
+ * @typedef {Object} ResponsesStreamOpts
+ * @property {string} apiBaseUrl   base URL ending without /responses
+ * @property {string} [apiKey]     optional bearer
+ * @property {string} model        model id
+ */
+
+const TOOL_NAME_FOR_OUTPUT_ITEM_PENDING = "__pending__";
+
+/**
+ * 拉一次 hermes-agent /v1/responses 流，逐 chunk yield。
+ *
+ * @param {Array<{role: string, content: any}>} messages
+ * @param {ResponsesStreamOpts} opts
+ */
+export async function* streamChat(messages, opts) {
+  const url = `${opts.apiBaseUrl.replace(/\/+$/, "")}/responses`;
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "text/event-stream",
+  };
+  if (opts.apiKey) headers.Authorization = `Bearer ${opts.apiKey}`;
+
+  // Responses API 请求体 —— hermes-agent 接受 OpenAI Responses 格式：
+  //   { model, input: messages, stream: true }
+  // 多模态 content array（image_url / file 等）原样透传 —— hermes-agent
+  // 内部走相同的 message normalization 逻辑。
+  const body = {
+    model: opts.model,
+    input: messages,
+    stream: true,
+  };
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: opts.signal,
+    });
+  } catch (err) {
+    yield { kind: "error", error: `fetch failed: ${err?.message || String(err)}` };
+    return;
+  }
+  if (!res.ok || !res.body) {
+    const text = await safeReadText(res);
+    yield {
+      kind: "error",
+      error: `responses backend HTTP ${res.status}: ${text.slice(0, 200)}`,
+    };
+    return;
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let pending = "";
+  let accum = "";
+  let usage = null;
+  // 缓存 function_call item id → call_id / name，用于把 done 时的 arguments
+  // 跟之前 added 时的 call_id 配对。
+  const pendingFunctionCalls = new Map(); // item_id → { call_id, name, arguments }
+
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      pending += decoder.decode(value, { stream: true });
+
+      // SSE 帧分隔符是空行（\n\n）。
+      let frameEnd;
+      while ((frameEnd = pending.indexOf("\n\n")) !== -1) {
+        const frame = pending.slice(0, frameEnd);
+        pending = pending.slice(frameEnd + 2);
+
+        let frameEvent = "";
+        const dataLines = [];
+        for (const rawLine of frame.split("\n")) {
+          const line = rawLine.replace(/\r$/, "");
+          if (line.startsWith(":")) continue;
+          if (line.startsWith("event:")) {
+            frameEvent = line.slice(6).trim();
+            continue;
+          }
+          if (line.startsWith("data:")) {
+            dataLines.push(line.slice(5).trim());
+          }
+        }
+        const payload = dataLines.join("\n");
+        if (!payload) continue;
+
+        // Responses API 不发 [DONE] sentinel — 用 response.completed/failed
+        // 作为终止信号。但兜底处理一下（部分代理可能加）。
+        if (payload === "[DONE]") {
+          yield { kind: "done", fullText: accum };
+          if (usage) yield { kind: "usage", usage };
+          return;
+        }
+
+        let parsed;
+        try {
+          parsed = JSON.parse(payload);
+        } catch {
+          continue; // 不可解析帧静默丢
+        }
+
+        const eventType = frameEvent || parsed?.type || "";
+
+        if (eventType === "response.output_text.delta") {
+          const delta = String(parsed.delta || "");
+          if (delta) {
+            accum += delta;
+            yield { kind: "delta", text: delta };
+          }
+        } else if (eventType === "response.reasoning_summary_text.delta") {
+          const delta = String(parsed.delta || "");
+          if (delta) yield { kind: "thinking", text: delta };
+        } else if (eventType === "response.output_item.added") {
+          const item = parsed.item || {};
+          const itemType = item.type;
+          if (itemType === "function_call") {
+            // tool 开始；arguments 在 added 时通常已经完整（hermes-agent 这边
+            // tool args 是同步 dispatch，不分片）—— 但稳妥起见也接受空 args，
+            // 然后等 output_item.done 给出最终 arguments 再 yield 真正的
+            // tool_call_started。这里只记录，不 yield。
+            const callId = String(item.call_id || "");
+            const name = String(item.name || "");
+            const args = String(item.arguments || "");
+            if (callId && name) {
+              pendingFunctionCalls.set(item.id || callId, {
+                call_id: callId,
+                name,
+                arguments: args,
+                yieldedStart: false,
+              });
+              // 如果 arguments 已经完整（非空），立即 yield —— App 可以更早看到
+              // tool 调用。这是 hermes-agent 当前的实际行为（dispatch 时一次
+              // 性写入），保险地处理 added 也带完整 args 的情形。
+              if (args) {
+                yield {
+                  kind: "tool_call_started",
+                  call_id: callId,
+                  name,
+                  arguments: args,
+                };
+                const entry = pendingFunctionCalls.get(item.id || callId);
+                if (entry) entry.yieldedStart = true;
+              }
+            }
+          } else if (itemType === "function_call_output") {
+            const callId = String(item.call_id || "");
+            // result 在 item.output[].text 里 —— api_server.py:1199 总是用
+            // {type: "input_text", text: <result_str>}。容错读 .output 数组。
+            let resultText = "";
+            const out = Array.isArray(item.output) ? item.output : [];
+            if (out.length > 0 && typeof out[0] === "object") {
+              resultText = String(out[0]?.text ?? "");
+            }
+            const isError = item.status === "failed";
+            // 从 pendingFunctionCalls 找对应 name（call_id 匹配，不一定按 item.id）
+            let name = TOOL_NAME_FOR_OUTPUT_ITEM_PENDING;
+            for (const v of pendingFunctionCalls.values()) {
+              if (v.call_id === callId) {
+                name = v.name;
+                break;
+              }
+            }
+            if (callId) {
+              yield {
+                kind: "tool_call_completed",
+                call_id: callId,
+                name,
+                result: resultText,
+                is_error: isError,
+              };
+            }
+          }
+          // 其它 item.type（message / reasoning）不发 chunk —— text 通过 delta 累积。
+        } else if (eventType === "response.output_item.done") {
+          const item = parsed.item || {};
+          if (item.type === "function_call") {
+            const callId = String(item.call_id || "");
+            const name = String(item.name || "");
+            const args = String(item.arguments || "");
+            const entry = pendingFunctionCalls.get(item.id || callId);
+            // 如果 added 时没 yield（没 args），现在补 yield tool_call_started
+            if (entry && !entry.yieldedStart) {
+              entry.yieldedStart = true;
+              entry.arguments = args;
+              yield {
+                kind: "tool_call_started",
+                call_id: callId,
+                name,
+                arguments: args,
+              };
+            }
+          }
+          // function_call_output.done 不需要额外动作 —— added 时已经发了
+          // tool_call_completed chunk。
+        } else if (eventType === "response.completed") {
+          // 终态 envelope 里带 usage 信息。
+          const u = parsed.response?.usage;
+          if (u && typeof u === "object") {
+            usage = u;
+          }
+          yield { kind: "done", fullText: accum };
+          if (usage) yield { kind: "usage", usage };
+          return;
+        } else if (eventType === "response.failed") {
+          const err =
+            parsed.response?.error?.message ||
+            parsed.message ||
+            "hermes-agent responses error";
+          yield { kind: "error", error: String(err) };
+          return;
+        }
+        // 其它事件类型（response.created / response.in_progress 等）静默忽略。
+      }
+    }
+    // Stream 结束但没看到 response.completed —— best-effort flush
+    if (accum) yield { kind: "done", fullText: accum };
+    if (usage) yield { kind: "usage", usage };
+  } catch (err) {
+    yield { kind: "error", error: `stream read failed: ${err?.message || String(err)}` };
+  } finally {
+    try { reader.releaseLock(); } catch {}
+  }
+}
+
+async function safeReadText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}