hermes-connect-services 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hawchou1995
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+# hermes-connect-services
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 zcode-ai-connect 的四个本地端点接进 [hermes](https://github.com/NousResearch/hermes-agent):打开 hermes 自动拉起服务,模型选择器里出现 Trae / WorkBuddy / Qoder / 千问办公四组模型。零依赖、零 API key、零按量计费。
+
+```
+hermes ──▶ 127.0.0.1:39272   zcode-trae-connect      ──▶ Trae CN
+      ──▶ 127.0.0.1:39271   zcode-workbuddy-connect ──▶ WorkBuddy
+      ──▶ 127.0.0.1:39270   zcode-qoder-connect     ──▶ Qoder CN
+      ──▶ 127.0.0.1:39269   zcode-qwenwork-connect  ──▶ 千问办公
+```
+
+## 一、安装
+
+```sh
+# 1. 同步 provider 到 hermes 的 config.yaml(从四个端点实时拉名册与 token)
+node hermes-connect-services/bin/sync-hermes-config.mjs
+
+# 2. 打开 hermes 自动拉起服务(写入 hooks.on_session_start)
+node hermes-connect-services/bin/sync-hermes-config.mjs --install-hooks
+```
+
+两步可以合成一次带 `--install-hooks` 的运行。配置文件位置自动探测：
+
+| 平台 | 路径 |
+|---|---|
+| Windows | `%LOCALAPPDATA%\hermes\config.yaml` |
+| 其他 | `~/.hermes/config.yaml` |
+| 覆盖 | 环境变量 `HERMES_HOME`,或 `--config <path>` |
+
+每次写盘前备份为 `config.yaml.bak`。
+
+## 二、写进去的东西
+
+脚本只碰三块**标记注释**之间的区域,其余字节一个不动(注释、缩进、你的手工配置全部保留):
+
+```yaml
+providers:
+  # >>> zcode-ai-connect >>>
+  zc-trae:
+    name: "Trae CN"
+    base_url: "http://127.0.0.1:39272/v1"
+    api_mode: "chat_completions"
+    api_key: "<端点 token>"
+    discover_models: false
+    request_timeout_seconds: 600
+    models:
+      "Doubao-Seed-2.1-Pro": {}
+      ...
+  # <<< zcode-ai-connect <<<
+
+model_overrides:
+  # >>> zcode-ai-connect >>>
+  zc-trae:
+    "Doubao-Seed-2.1-Pro":
+      context_window: 1000000
+      supports_tools: true
+      supports_reasoning: true
+      supports_vision: false
+  # <<< zcode-ai-connect <<<
+
+hooks:
+  # >>> zcode-ai-connect >>>
+  on_session_start:
+    - command: '"<node.exe>" "<...>/ensure-services.mjs"'
+      timeout: 30
+  # <<< zcode-ai-connect <<<
+```
+
+- provider id 一律 `zc-` 前缀,与 hermes 内建(openrouter / nous / gemini …)和你自己写的 provider 互不干扰;
+- `discover_models: false` —— 模型清单在同步时就写死,hermes 不必为了渲染选择器去探测一个没启动的 sidecar;
+- `request_timeout_seconds: 600` —— 长思考模型排队到首帧可能要 90 秒,默认超时会掐掉合法请求;
+- `--only <id>` 只重写指定 provider,其余托管内容原样保留。
+
+## 三、选模型
+
+```
+/model                                   # 交互选择
+hermes --provider zc-workbuddy --model deepseek-v4.1-flash
+```
+
+或在 `config.yaml` 里直接改默认:
+
+```yaml
+model:
+  provider: zc-workbuddy
+  default: deepseek-v4.1-flash
+  base_url: http://127.0.0.1:39271/v1
+```
+
+## 四、命令
+
+| 命令 | 作用 |
+|---|---|
+| `node bin/sync-hermes-config.mjs` | 同步四个 provider 的模型名册与 token |
+| `… --install-hooks` | 额外写入 `hooks.on_session_start` 懒启动 |
+| `… --remove` | 移除本工具在 config.yaml 里的全部托管块(干净卸载) |
+| `… --only zc-trae` | 只同步一个端点 |
+| `… --ensure` | 同步前先把没起来的端点拉起来 |
+| `… --dry-run` | 只打印要改什么,不写盘 |
+| `… --no-reasoning` | 全部模型标 `supports_reasoning: false` |
+| `… --config <path>` | 指定配置文件 |
+| `node bin/ensure-services.mjs [--verbose]` | 单独执行懒启动(也是 hook 本体) |
+
+## 五、排障
+
+**401 / 模型不在了** — 端点 token 轮换或上游名册变了,重跑 `sync-hermes-config.mjs`。
+
+**hook 第一次不执行** — hermes 首次运行 hook 需要交互确认。非交互场景在 config.yaml 设:
+
+```yaml
+hooks_auto_accept: true
+```
+
+**连不上回环地址(`404 no such route` 带绝对 URL、**或 connection refused)** — hermes 是 Python + httpx,会读 `HTTP_PROXY` / `HTTPS_PROXY`。这些变量存在时本地请求会被送去代理,回环地址自然打不通。启动时带上 no_proxy:
+
+```sh
+NO_PROXY=127.0.0.1,localhost   # PowerShell: $env:NO_PROXY="127.0.0.1,localhost"
+```
+
+**Thoughts 太长被压缩** — `model_overrides` 里的 `context_window` 来自端点实时 roster;换模型名后重跑同步脚本同步上下文窗口。
+
+**思考档位** — hermes 全局 `agent.reasoning_effort` 默认 `ultra`,这些端点会原样转发 OpenAI 的 `reasoning_effort`。上游不认 `ultra` 时把它降到 `high`。不想让任何模型思考就加 `--no-reasoning`。
+
+## 六、测试
+
+```sh
+node hermes-connect-services/tests/test-yaml-patch.mjs
+```
+
+覆盖的是最危险的那部分:托管块插入/替换/卸载、幂等性、`--only` 不删邻居、孤儿标记自愈。
+
+---
+
+MIT License — 见仓库 [LICENSE](../LICENSE)。

package/bin/ensure-services.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * ensure-services.mjs — bring the four loopback endpoints up if they are down.
+ *
+ * This is the hermes-side half of the suite's launch-on-open design: each
+ * plugin expects something to be listening on its fixed port before the first
+ * message goes out, because the provider entry in hermes' config.yaml points
+ * at that port.
+ *
+ * It is installed as a hermes shell hook on `on_session_start` (see
+ * `--install-hooks` on sync-hermes-config.mjs) and it is safe to run by hand.
+ *
+ * Contract with hermes' shell-hook runner:
+ *   - stdin receives a JSON payload → drain it so nothing blocks;
+ *   - stdout must be empty or a JSON object → we print diagnostics to stderr
+ *     only, so `--verbose` debugging never risks being parsed as a directive;
+ *   - always exits 0 — a hook that fails the session because it could not
+ *     start a sidecar would be worse than no hook.
+ *
+ * Usage:
+ *   node ensure-services.mjs [--verbose] [--only zc-trae]
+ */
+
+import { SERVICES, ensure, log } from '../src/services.mjs';
+
+const argv = process.argv.slice(2);
+const verbose = argv.includes('--verbose') || argv.includes('-v');
+const only = argv.includes('--only') ? argv[argv.indexOf('--only') + 1] : null;
+const targets = only ? SERVICES.filter((s) => s.id === only || s.tool === only) : SERVICES;
+
+const say = (line) => process.stderr.write(`${line}\n`);
+
+// hermes writes a hook payload to stdin; nothing here reads it, but leaving it
+// undrained risks a full pipe on some platforms.
+process.stdin.resume().on('data', () => {});
+
+if (targets.length === 0) {
+  say(`[hermes-connect-services] unknown --only target: ${only}`);
+  process.exit(0);
+}
+
+const results = await Promise.all(targets.map(async (service) => {
+  const result = await ensure(service);
+  await log(service, `[hermes] ensure: ${result.action}${result.up ? '' : ` (not reachable on :${result.port})`}`);
+  return result;
+}));
+
+if (verbose) {
+  say('[hermes-connect-services]');
+  for (const r of results) say(`  ${r.service.id.padEnd(13)} :${r.port}  ${r.up ? 'up  ' : 'DOWN'}  ${r.action}`);
+} else {
+  const down = results.filter((r) => !r.up);
+  if (down.length > 0) {
+    say(`[hermes-connect-services] ${down.length}/${results.length} endpoint(s) unreachable: ${down.map((r) => r.service.id).join(', ')}`);
+    say('  Their models will fail until started. Start one manually with:');
+    for (const r of down) say(`    node "${import.meta.dirname}/../../${r.service.tool}/bin/cli.mjs" serve --port ${r.port}`);
+    say('  ...or re-run this script with --verbose.');
+  }
+}
+
+process.exit(0);

package/bin/sync-hermes-config.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+/**
+ * sync-hermes-config.mjs — publish the four loopback endpoints into hermes'
+ * config.yaml as OpenAI-compatible custom providers.
+ *
+ * Writes exactly three managed regions and touches nothing else:
+ *
+ *   providers.<id>       — base_url / bearer token / model allowlist
+ *   model_overrides.<id> — context window, tools, vision, reasoning
+ *   hooks.on_session_start (optional, `--install-hooks`) — lazy-start script
+ *
+ * Everything outside those marker comments (vm blocks, platform tokens,
+ * MQTT chat settings, hand-written providers) survives untouched — the file is
+ * patched as text, never re-serialised from a parsed tree.
+ *
+ * A backup of the pre-run file lands next to it as `<name>.bak`.
+ *
+ * Usage:
+ *   node sync-hermes-config.mjs [--dry-run] [--ensure] [--install-hooks]
+ *                               [--remove] [--only <zc-id>] [--config <path>]
+ *                               [--no-reasoning] [--verbose]
+ */
+
+import { copyFileSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname as pathDirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SERVICES, HOME, SUITE_ROOT, ensure as ensureService } from '../src/services.mjs';
+import { loadRoster, describe } from '../src/roster.mjs';
+import { patchManagedBlock, readManagedBlock, readManagedChildren } from '../src/yaml-patch.mjs';
+
+const HERE = pathDirname(fileURLToPath(import.meta.url));
+const MARKER = 'zcode-ai-connect';
+
+const argv = process.argv.slice(2);
+const flag = (name) => argv.includes(name);
+const value = (name) => (argv.includes(name) ? argv[argv.indexOf(name) + 1] : null);
+
+const options = {
+  dryRun: flag('--dry-run') || flag('-n'),
+  ensure: flag('--ensure'),
+  installHooks: flag('--install-hooks'),
+  remove: flag('--remove'),
+  noReasoning: flag('--no-reasoning'),
+  verbose: flag('--verbose') || flag('-v'),
+  only: value('--only'),
+  config: value('--config'),
+};
+
+/** hermes keeps its user config in %LOCALAPPDATA%/hermes on Windows, ~/.hermes elsewhere. */
+function locateConfig() {
+  if (options.config) return options.config;
+  const candidates = [
+    process.env.HERMES_HOME ? join(process.env.HERMES_HOME, 'config.yaml') : null,
+    process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, 'hermes', 'config.yaml') : null,
+    join(HOME, '.hermes', 'config.yaml'),
+  ].filter(Boolean);
+  return candidates.find((p) => existsSync(p)) ?? candidates[candidates.length - 1];
+}
+
+const CONFIG_PATH = locateConfig();
+
+/**
+ * True when the file already binds an `on_session_start` hook outside our
+ * managed region — i.e. one the user wrote, which we must not displace.
+ */
+function ownsHookSlot(text) {
+  const lines = text.split(/\r?\n/);
+  const key = lines.findIndex((line) => /^hooks\s*:\s*(#.*)?$/.test(line));
+  if (key === -1) return false;
+  let end = lines.length;
+  for (let i = key + 1; i < lines.length; i += 1) {
+    if (/^\S/.test(lines[i]) && lines[i].trim() !== '') {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(key + 1, end).some((line) => /^\s+on_session_start\s*:/.test(line));
+}
+
+/** YAML double-quoted scalar — safe for ids containing `#`, `:` or leading dashes. */
+const q = (input) => `"${String(input).replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+
+/**
+ * One provider entry. `discover_models: false` is deliberate: the allowlist is
+ * written from the live roster at sync time, so hermes never has to probe a
+ * stopped sidecar to render its picker.
+ */
+function providerBlockYaml(service, roster, models) {
+  const lines = [
+    `${service.id}:`,
+    `  name: ${q(service.name)}`,
+    `  base_url: ${q(roster.baseUrl)}`,
+    `  api_mode: "chat_completions"`,
+    `  api_key: ${q(roster.token)}`,
+    `  discover_models: false`,
+    // Long thinking bursts are normal on these models; the default request
+    // timeout would abort a legitimate 90s queue wait.
+    `  request_timeout_seconds: 600`,
+    `  models:`,
+  ];
+  for (const model of models) lines.push(`    ${q(model.id)}: {}`);
+  return lines;
+}
+
+function overridesBlockYaml(service, models) {
+  if (models.length === 0) return null;
+  const lines = [`${service.id}:`];
+  for (const model of models) {
+    lines.push(`  ${q(model.id)}:`);
+    if (model.contextWindow) lines.push(`    context_window: ${model.contextWindow}`);
+    lines.push(`    supports_tools: true`);
+    lines.push(`    supports_reasoning: ${options.noReasoning ? 'false' : String(model.supportsReasoning)}`);
+    lines.push(`    supports_vision: ${String(model.supportsVision)}`);
+  }
+  return lines;
+}
+
+function hooksBlockYaml() {
+  const nodeExe = process.execPath.replaceAll('\\', '/');
+  const script = join(HERE, 'ensure-services.mjs').replaceAll('\\', '/');
+  // shlex.split + shell=False: the token that reaches Popen must keep both
+  // paths quoted, so the whole value is single-quoted YAML rather than two
+  // adjacent double-quoted scalars (which YAML rejects outright).
+  const command = `'${`"${nodeExe}" "${script}"`}'`;
+  return [
+    `on_session_start:`,
+    `  - command: ${command}`,
+    `    timeout: 30`,
+  ];
+}
+
+// --- collect rosters --------------------------------------------------------
+
+const targets = options.only
+  ? SERVICES.filter((s) => s.id === options.only || s.tool === options.only)
+  : SERVICES;
+if (targets.length === 0) {
+  console.error(`[sync-hermes] unknown --only target: ${options.only}`);
+  console.error(`  known ids: ${SERVICES.map((s) => s.id).join(', ')}`);
+  process.exit(1);
+}
+
+const collected = [];
+for (const service of targets) {
+  if (options.ensure) {
+    const started = await ensureService(service);
+    if (options.verbose) {
+      console.log(`  ${service.id.padEnd(13)} :${started.port}  ${started.up ? 'up  ' : 'DOWN'}  ${started.action}`);
+    }
+  }
+  try {
+    const roster = await loadRoster(service);
+    const models = roster.rows.map((row) => describe(row, { assumeReasoning: !options.noReasoning }));
+    collected.push({ service, roster, models });
+  } catch (error) {
+    console.log(`  ${service.id.padEnd(13)} skipped — ${String(error.message ?? error).slice(0, 90)}`);
+  }
+}
+
+if (collected.length === 0) {
+  console.error(`[sync-hermes] no endpoint answered; nothing written to ${CONFIG_PATH}`);
+  console.error(`  Start them first, or re-run with --ensure.`);
+  process.exit(1);
+}
+
+// --- patch ------------------------------------------------------------------
+
+/**
+ * Rebuild one region, keeping the blocks this run did not touch.
+ *
+ * `--only zc-trae` must not delete the other three providers, so existing
+ * children are read back first and only the targeted ids are overwritten.
+ */
+function mergeInto(originalText, key, updates) {
+  const existing = new Map(readManagedChildren(originalText, key, { marker: MARKER }).map((b) => [b.key, b.body]));
+  const touched = new Set();
+  for (const [childKey, body] of updates) {
+    existing.set(childKey, body);
+    touched.add(childKey);
+  }
+  return {
+    body: [...existing.values()].join('\n'),
+    action: touched.size < updates.length ? 'partial' : null,
+  };
+}
+
+const original = readFileSync(CONFIG_PATH, 'utf8');
+let text = original;
+
+if (options.remove) {
+  for (const key of ['providers', 'model_overrides', 'hooks']) {
+    const result = patchManagedBlock(text, key, '', { marker: MARKER });
+    text = result.text;
+  }
+} else {
+  const providerUpdates = [];
+  const overrideUpdates = [];
+  for (const entry of collected) {
+    providerUpdates.push([entry.service.id, providerBlockYaml(entry.service, entry.roster, entry.models).join('\n')]);
+    const overrides = overridesBlockYaml(entry.service, entry.models);
+    if (overrides) overrideUpdates.push([entry.service.id, overrides.join('\n')]);
+  }
+
+  const changes = [];
+  for (const [key, updates] of [
+    ['providers', providerUpdates],
+    ['model_overrides', overrideUpdates],
+  ]) {
+    const merged = mergeInto(original, key, updates);
+    const result = patchManagedBlock(text, key, merged.body, { marker: MARKER });
+    text = result.text;
+    changes.push(`${key}: ${result.action}${options.only ? ` (only ${options.only})` : ''}`);
+  }
+
+  if (options.installHooks) {
+    const body = hooksBlockYaml().join('\n');
+    if (readManagedBlock(text, 'hooks', { marker: MARKER }).trim() !== '') {
+      text = patchManagedBlock(text, 'hooks', body, { marker: MARKER }).text;
+      changes.push('hooks: replaced');
+    } else if (ownsHookSlot(original)) {
+      // Someone already hangs a hook on this event. Taking the slot silently
+      // would be the kind of surprise that ends with a deleted screenshot.
+      console.log('hooks: 已有非托管的 on_session_start 条目 — 跳过(用 --remove 清托管块后手动合并)');
+    } else {
+      const result = patchManagedBlock(text, 'hooks', body, { marker: MARKER });
+      text = result.text;
+      changes.push(`hooks: ${result.action}`);
+    }
+  }
+  console.log(changes.map((line) => `  ${line}`).join('\n'));
+}
+
+if (text === original) {
+  console.log('  nothing changed');
+} else if (options.dryRun) {
+  console.log(`  --dry-run: ${CONFIG_PATH} not written`);
+} else {
+  copyFileSync(CONFIG_PATH, `${CONFIG_PATH}.bak`);
+  writeFileSync(CONFIG_PATH, text, 'utf8');
+  console.log(`  wrote ${CONFIG_PATH}(backup: ${CONFIG_PATH}.bak)`);
+}
+
+// --- report -----------------------------------------------------------------
+
+console.log('');
+for (const entry of collected) {
+  console.log(`${entry.service.id.padEnd(13)} ${String(entry.models.length).padStart(3)} models @ ${entry.roster.baseUrl}`);
+}
+console.log('');
+console.log('选择模型: hermes 里 `/model`,或直接');
+console.log(`  ${CONFIG_PATH.replaceAll('\\', '/')}  -> model.provider: ${collected[0].service.id}`);
+console.log(`  hermes --provider ${collected[0].service.id} --model <id>`);
+console.log('');
+console.log('Token 轮换(报 401)或上游名册变化时,重跑本脚本即可。');
+
+if (options.installHooks && !options.remove && !options.dryRun) {
+  const autoAccept = readFileSync(CONFIG_PATH, 'utf8').match(/^hooks_auto_accept:\s*(.+)$/m)?.[1]?.trim();
+  if (autoAccept !== 'true') {
+    console.log('');
+    console.log(`提示: 首次运行 hook 需要交互确认。非交互场景请在 ${CONFIG_PATH} 设置 hooks_auto_accept: true`);
+    console.log('      (当前值: ' + (autoAccept ?? '未设置') + ')');
+  }
+}
+
+if (options.remove) {
+  console.log('');
+  console.log(`已移除 ${CONFIG_PATH} 中的 ${MARKER} 托管块${options.dryRun ? ' (--dry-run: 未写盘)' : ''}`);
+  console.log(`  suite root: ${SUITE_ROOT}`);
+  console.log(`  config:     ${dirname(CONFIG_PATH)}`);
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "hermes-connect-services",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Bring zcode-ai-connect's four loopback endpoints to hermes: lazy-start them on session start and sync them into hermes' config.yaml as OpenAI-compatible providers.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "xiao-hans",
+    "url": "https://github.com/xiao-hans"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xiao-hans/zcode-ai-connect.git",
+    "directory": "hermes-connect-services"
+  },
+  "homepage": "https://github.com/xiao-hans/zcode-ai-connect/tree/main/hermes-connect-services#readme",
+  "bugs": {
+    "url": "https://github.com/xiao-hans/zcode-ai-connect/issues"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "hermes-connect-ensure": "bin/ensure-services.mjs",
+    "hermes-connect-sync": "bin/sync-hermes-config.mjs"
+  },
+  "dependencies": {},
+  "keywords": [
+    "hermes",
+    "openai-compatible",
+    "loopback",
+    "trae",
+    "workbuddy",
+    "qoder",
+    "qwenwork"
+  ]
+}

package/src/roster.mjs

@@ -0,0 +1,64 @@
+/**
+ * Read each endpoint's live model roster.
+ *
+ * `/v1/models` is the only source of truth here: the tool's own static catalog
+ * files drift (a model can go LOCKED, get renamed, or gain an image input
+ * overnight), and the bearer token rotates. Everything the hermes provider
+ * entry needs comes from one probe.
+ *
+ * @module hermes-connect-services/src/roster
+ */
+
+import { readEndpoint } from './services.mjs';
+
+/**
+ * @param {object} service
+ * @returns {Promise<{ baseUrl: string, token: string, port: number, rows: Array<object> }>}
+ * @throws when the endpoint is unreachable or answers non-200.
+ */
+export async function loadRoster(service, { timeoutMs = 5000 } = {}) {
+  const { token, port } = await readEndpoint(service);
+  const response = await fetch(`http://127.0.0.1:${port}/v1/models`, {
+    headers: token === '' ? {} : { Authorization: `Bearer ${token}` },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!response.ok) {
+    throw new Error(`/v1/models -> ${response.status} (端点没跑?先 serve)`);
+  }
+  const json = await response.json();
+  return {
+    baseUrl: `http://127.0.0.1:${port}/v1`,
+    token,
+    port,
+    rows: Array.isArray(json?.data) ? json.data : [],
+  };
+}
+
+/**
+ * Normalise one roster row into what hermes needs.
+ *
+ * hermes' own picker will happily serve a bare id, but context window,
+ * tool-calling and vision are what decide whether a long session survives:
+ * get the context window wrong and compression fires halfway through a turn.
+ */
+export function describe(row, { assumeReasoning = true } = {}) {
+  const context = Number.isInteger(row.context_window) && row.context_window > 0
+    ? row.context_window
+    : undefined;
+  const output = Number.isInteger(row.max_output_tokens) && row.max_output_tokens > 0
+    ? row.max_output_tokens
+    : undefined;
+  return {
+    id: row.id,
+    displayName: row.display_name ?? row.id,
+    contextWindow: context,
+    maxOutputTokens: output,
+    supportsVision: row.supports_images === true,
+    // The endpoints forward OpenAI's `reasoning_effort` verbatim, so declaring
+    // support is accurate for every model they expose; `--no-reasoning`
+    // downgrades the whole provider when a user prefers plain answers.
+    supportsReasoning: row.supports_images === false && row.id.startsWith('Doubao-')
+      ? false
+      : assumeReasoning,
+  };
+}

package/src/services.mjs

@@ -0,0 +1,152 @@
+/**
+ * The four loopback endpoints this suite serves, described once so the ensure
+ * script and the config sync agree on ports, state dirs and provider ids.
+ *
+ * Provider ids are prefixed with `zc-` so they can never collide with a
+ * hermes built-in (openrouter / nous / gemini / …) or with a provider the user
+ * already declared by hand. Everything else about the entry is derived at sync
+ * time from the live endpoint, which is the only source of truth for the
+ * roster and the bearer token.
+ *
+ * @module hermes-connect-services/src/services
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { mkdir, appendFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Suite root = parent of this directory; overridable for relocation/tests. */
+export const SUITE_ROOT = resolve(
+  process.env.AI_CONNECT_SUITE_ROOT ?? dirname(dirname(dirname(fileURLToPath(import.meta.url)))),
+);
+
+export const SERVICES = [
+  {
+    id: 'zc-qwenwork',
+    name: '千问办公 (QwenWork)',
+    tool: 'zcode-qwenwork-connect',
+    port: 39269,
+    state: '.zcode-qwenwork-connect',
+  },
+  {
+    id: 'zc-qoder',
+    name: 'Qoder CN',
+    tool: 'zcode-qoder-connect',
+    port: 39270,
+    state: '.zcode-qoder-connect',
+  },
+  {
+    id: 'zc-workbuddy',
+    name: 'WorkBuddy',
+    tool: 'zcode-workbuddy-connect',
+    port: 39271,
+    state: '.zcode-workbuddy-connect',
+  },
+  {
+    id: 'zc-trae',
+    name: 'Trae CN',
+    tool: 'zcode-trae-connect',
+    port: 39272,
+    state: '.zcode-trae-connect',
+  },
+];
+
+export const HOME = process.env.USERPROFILE ?? process.env.HOME ?? '.';
+
+export const cliPath = (service) => join(SUITE_ROOT, service.tool, 'bin', 'cli.mjs');
+export const toolRoot = (service) => join(SUITE_ROOT, service.tool);
+export const stateDir = (service) => join(HOME, service.state);
+
+/** Read `{token, port}` from the tool's state dir, falling back to its default port. */
+export async function readEndpoint(service) {
+  try {
+    const document = JSON.parse(await readFile(join(stateDir(service), 'endpoint.json'), 'utf8'));
+    const token = typeof document.token === 'string' ? document.token : '';
+    const port = Number.isInteger(document.port) && document.port > 0 ? document.port : service.port;
+    return { token, port };
+  } catch {
+    return { token: '', port: service.port };
+  }
+}
+
+/** True only when the endpoint answers healthily — the same contract as every plugin's hook. */
+export async function healthy(port, token, timeoutMs = 1500) {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/healthz`, {
+      headers: token === '' ? {} : { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) return false;
+    const body = await response.json();
+    return body?.ok === true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForHealth(port, token, attempts = 20) {
+  for (let i = 0; i < attempts; i += 1) {
+    if (await healthy(port, token)) return true;
+    await new Promise((done) => setTimeout(done, 500));
+  }
+  return false;
+}
+
+/**
+ * Detached, windowless, best-effort start.
+ *
+ * `windowsHide` plus `stdio: 'ignore'` matters: a session-start hook that
+ * flashes four console windows would be worse than no hook at all.
+ */
+function spawnDetached(service, port) {
+  const child = spawn(process.execPath, [cliPath(service), 'serve', '--port', String(port)], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+    cwd: toolRoot(service),
+  });
+  child.unref();
+  return child.pid;
+}
+
+/**
+ * Ensure one endpoint is up. Never throws — the session must go on even when
+ * the host refuses to spawn.
+ *
+ * @returns {{ service: object, port: number, token: string, up: boolean, action: string, pid?: number }}
+ */
+export async function ensure(service) {
+  const { token, port } = await readEndpoint(service);
+  const base = { service, port, token };
+
+  if (!existsSync(cliPath(service))) {
+    return { ...base, up: false, action: `not installed (missing ${cliPath(service)})` };
+  }
+  if (await healthy(port, token)) {
+    return { ...base, up: true, action: 'already up' };
+  }
+
+  let pid;
+  try {
+    pid = spawnDetached(service, port);
+  } catch (error) {
+    return { ...base, up: false, action: `spawn refused: ${String(error).slice(0, 80)}` };
+  }
+  if (await waitForHealth(port, token)) {
+    return { ...base, up: true, action: 'started', pid };
+  }
+  return { ...base, up: false, action: `did not become healthy on :${port}`, pid };
+}
+
+/** Best-effort transcript for hook debugging; never allowed to throw. */
+export async function log(service, line) {
+  try {
+    await mkdir(stateDir(service), { recursive: true });
+    await appendFile(join(stateDir(service), 'service.log'), `${new Date().toISOString()} ${line}\n`);
+  } catch {
+    // Diagnostics are optional.
+  }
+}

package/src/yaml-patch.mjs

@@ -0,0 +1,212 @@
+/**
+ * YAML managed-block patcher — zero dependencies, text-in/text-out.
+ *
+ * hermes' config.yaml is hand-edited YAML: comments, ordering and quoting all
+ * carry meaning for whoever reads it next. A generic YAML round-trip would
+ * rewrite the whole file on every sync, so this module does the narrowest
+ * thing that can work:
+ *
+ *   - insert / replace *one block per top-level mapping key*, delimited by a
+ *     marker comment pair;
+ *   - leave every other byte of the file untouched.
+ *
+ * Blocks are idempotent: the managed region is torn down and rewritten on each
+ * run, so removing a provider from the roster really removes it from the
+ * config instead of leaving a stale entry behind.
+ *
+ * @module hermes-connect-services/src/yaml-patch
+ */
+
+const START = (marker) => `# >>> ${marker} >>>`;
+const END = (marker) => `# <<< ${marker} <<<`;
+
+/**
+ * Replace the managed region inside one top-level mapping key.
+ *
+ * @param {string} text          Whole config file.
+ * @param {string} topKey        Top-level mapping key, e.g. `providers`.
+ * @param {string} blockBody     Already-indented YAML lines (2 spaces) to host,
+ *                               without the parent key itself. `''` removes the
+ *                               region and nothing else.
+ * @param {{ marker?: string, indent?: string }} [options]
+ * @returns {{ text: string, changed: boolean, action: 'inserted'|'replaced'|'removed'|'noop' }}
+ */
+export function patchManagedBlock(text, topKey, blockBody, options = {}) {
+  const marker = options.marker ?? 'zcode-ai-connect';
+  const indent = options.indent ?? '  ';
+  const startToken = START(marker);
+  const endToken = END(marker);
+
+  const lines = text.split(/\r?\n/);
+  const keyIndex = findTopLevelKey(lines, topKey);
+
+  if (keyIndex === -1) {
+    if (blockBody.trim() === '') return { text, changed: false, action: 'noop' };
+    return {
+      text: appendKeyBlock(text, topKey, blockBody, { marker, indent }),
+      changed: true,
+      action: 'inserted',
+    };
+  }
+
+  // An inline empty map (`providers: {}`) is legal YAML but has nowhere to put
+  // children — turn it into a block before patching.
+  if (isInlineEmptyMap(lines[keyIndex])) lines[keyIndex] = `${topKey}:`;
+
+  const region = mappingRegion(lines, keyIndex);
+  const owned = findManagedRegion(lines, region, startToken, endToken);
+  const nextBlock = buildManagedBlock(blockBody, { marker, indent });
+
+  if (owned) {
+    const replacement = nextBlock; // '' when the caller wants it gone
+    const before = lines.join('\n');
+    lines.splice(owned.start, owned.end - owned.start + 1, ...replacement);
+    const after = lines.join('\n');
+    return {
+      text: after,
+      // Rewriting an identical region is not a change: callers (and their
+      // backups) must not churn just because sync ran twice.
+      changed: after !== before,
+      action: replacement.length === 0 ? 'removed' : 'replaced',
+    };
+  }
+
+  if (nextBlock.length === 0) return { text, changed: false, action: 'noop' };
+  lines.splice(region.end, 0, ...nextBlock);
+  return { text: lines.join('\n'), changed: true, action: 'inserted' };
+}
+
+/**
+ * Read back what is currently inside one managed region — used by `--diff`
+ * reports and by tests. Returns '' when absent.
+ */
+export function readManagedBlock(text, topKey, options = {}) {
+  const marker = options.marker ?? 'zcode-ai-connect';
+  const lines = text.split(/\r?\n/);
+  const keyIndex = findTopLevelKey(lines, topKey);
+  if (keyIndex === -1) return '';
+  const region = mappingRegion(lines, keyIndex);
+  const owned = findManagedRegion(lines, region, START(marker), END(marker));
+  if (!owned) return '';
+  return lines.slice(owned.start + 1, owned.end).join('\n');
+}
+
+/**
+ * Split a managed region into its per-child blocks, keyed by the child's name.
+ *
+ * Needed for partial syncs (`--only zc-trae`): the region is rewritten whole,
+ * so without this the three untouched providers would be dropped on the floor.
+ *
+ * @returns {Array<{ key: string, body: string }>}
+ */
+export function readManagedChildren(text, topKey, options = {}) {
+  const marker = options.marker ?? 'zcode-ai-connect';
+  const lines = text.split(/\r?\n/);
+  const keyIndex = findTopLevelKey(lines, topKey);
+  if (keyIndex === -1) return [];
+  const region = mappingRegion(lines, keyIndex);
+  const owned = findManagedRegion(lines, region, START(marker), END(marker));
+  if (!owned) return [];
+  // Inside `providers:` the region carries the mapping's 2-space indent; strip
+  // the common prefix before looking for column-0 child keys.
+  return splitBlocks(dedent(lines.slice(owned.start + 1, owned.end)));
+}
+
+/** Remove the shortest common leading indent shared by every non-blank line. */
+function dedent(lines) {
+  const indents = lines
+    .filter((line) => line.trim() !== '')
+    .map((line) => line.length - line.trimStart().length);
+  const shift = indents.length === 0 ? 0 : Math.min(...indents);
+  return shift === 0 ? lines : lines.map((line) => (line.trim() === '' ? line : line.slice(shift)));
+}
+
+/** True when the top-level mapping key exists at all. */
+export function hasTopLevelKey(text, topKey) {
+  return findTopLevelKey(text.split(/\r?\n/), topKey) !== -1;
+}
+
+// --- internals -------------------------------------------------------------
+
+/** Index of a top-level `key:` line, or -1. Inline keys inside blocks never match. */
+function findTopLevelKey(lines, topKey) {
+  const escaped = topKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`^${escaped}\\s*:\\s*(#.*)?$`);
+  return lines.findIndex((line) => pattern.test(line));
+}
+
+function isInlineEmptyMap(line) {
+  return /:\s*\{\s*\}\s*(#.*)?$/.test(line);
+}
+
+/**
+ * Line range owned by the mapping that starts at `keyIndex`: everything after
+ * the key line until the next top-level key (or EOF). Trailing blank lines are
+ * excluded so inserted blocks land right after the last real child.
+ */
+function mappingRegion(lines, keyIndex) {
+  let end = lines.length;
+  for (let i = keyIndex + 1; i < lines.length; i += 1) {
+    if (/^\S/.test(lines[i]) && lines[i].trim() !== '') {
+      end = i;
+      break;
+    }
+  }
+  while (end - 1 > keyIndex && lines[end - 1].trim() === '') end -= 1;
+  return { start: keyIndex + 1, end };
+}
+
+function findManagedRegion(lines, region, startToken, endToken) {
+  let start = -1;
+  for (let i = region.start; i < region.end; i += 1) {
+    if (lines[i].trim() === startToken) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) return null;
+  for (let i = start; i < region.end; i += 1) {
+    if (lines[i].trim() === endToken) return { start, end: i };
+  }
+  // Unterminated marker (hand edit gone wrong) — claim up to the region end so
+  // the next sync repairs it deterministically.
+  return { start, end: region.end - 1 };
+}
+
+function buildManagedBlock(blockBody, { marker, indent }) {
+  const body = blockBody.replace(/\s+$/, '');
+  if (body === '') return [];
+  return [
+    `${indent}${START(marker)}`,
+    ...body.split('\n').map((line) => (line === '' ? '' : `${indent}${line}`)),
+    `${indent}${END(marker)}`,
+  ];
+}
+
+/**
+ * Cut a list of already-dedented lines into top-level blocks. A block starts at
+ * a column-0 `key:` line and runs to the next one.
+ */
+function splitBlocks(body) {
+  const blocks = [];
+  let current = null;
+  for (const line of body) {
+    if (/^\S/.test(line) && /^\S[^#]*:\s*$/.test(line)) {
+      if (current) blocks.push(current);
+      current = { key: line.replace(/:\s*$/, ''), lines: [line] };
+      continue;
+    }
+    if (current) current.lines.push(line);
+  }
+  if (current) blocks.push(current);
+  return blocks.map(({ key, lines }) => ({
+    key,
+    body: lines.join('\n').replace(/\s+$/, ''),
+  }));
+}
+
+function appendKeyBlock(text, topKey, blockBody, { marker, indent }) {
+  const head = text.replace(/\s+$/, '');
+  const block = buildManagedBlock(blockBody, { marker, indent });
+  return [`${head}`, '', `${topKey}:`, ...block, ''].join('\n');
+}