harness-mix 0.1.0

package/src/main/adapters/grok.js

@@ -0,0 +1,161 @@
+const { execFile } = require('node:child_process');
+const { randomUUID } = require('node:crypto');
+const { JsonlProcess, cliSpawn } = require('../host/jsonl');
+
+const textOf = content => Array.isArray(content) ? content.map(c => c.text ?? c.content?.text ?? '').filter(Boolean).join('\n') : content?.text || '';
+function catalog(session) {
+  const options = session.state.configOptions || [];
+  const modelConfig = options.find(o => o.category === 'model');
+  const modeConfig = options.find(o => o.category === 'mode');
+  const nativeModels = session.state.models?.availableModels || [];
+  const models = modelConfig ? (modelConfig.options || []).filter(o => o.value).map(o => ({ id: o.value, name: o.name, isDefault: o.value === modelConfig.currentValue }))
+    : nativeModels.map(m => ({ id: m.modelId, name: m.name || m.modelId, isDefault: m.modelId === session.state.models?.currentModelId }));
+  const current = nativeModels.find(m => m.modelId === session.state.models?.currentModelId);
+  return { models,
+    thinkingLevels: (current?._meta?.reasoningEfforts || []).map(e => ({ id: e.id, label: e.label || e.id })),
+    permissionModes: modeConfig ? (modeConfig.options || []).map(o => ({ id: o.value, label: o.name, description: o.description, default: o.value === modeConfig.currentValue }))
+      : (session.state.modes?.availableModes || []).map(m => ({ id: m.id, label: m.name, default: m.id === session.state.modes.currentModeId })),
+  };
+}
+
+function grokAdapter() {
+  const id = 'grok', name = 'Grok', bin = process.env.HARNESS_MIX_GROK_EXECUTABLE || 'grok.exe', args = ['agent', 'stdio'], executable = true, images = true, fork = true, thinking = true, permissions = false;
+  const manifest = { id, name, icon: `${id}-color.svg`, aliases: [id], capabilities: { collaborationTools: true, streaming: true, thinking: true, tools: true, approvals: true,
+    questions: false, models: true, thinkingLevels: thinking, permissionModes: permissions, resume: true, fork, forkFromMessage: false,
+    compaction: true, usage: true, contextUsage: false, attachments: images } };
+  const command = argv => executable ? { command: bin, args: argv } : cliSpawn(bin, argv);
+  function create() {
+    const adapter = {
+      async inspect() {
+        const cli = command(['--version']);
+        return new Promise(resolve => execFile(cli.command, cli.args, { windowsHide: true, timeout: 10000 }, (error, out) => resolve({ available: !error, detail: error ? `${name} CLI 不可用` : out.trim() })));
+      },
+      async describe() { return { models: null, thinkingLevels: [], permissionModes: [] }; },
+      async open({ thread, emit, diagnostic = () => {}, collaboration }) {
+        const cli = command(args);
+        const session = { cwd: thread.cwd, nativeSessionId: null, collaborationEnabled: !!collaboration, state: { configOptions: [], models: null, modes: null, commands: [], usage: undefined, loading: true }, pendingApprovals: new Map(), tools: new Map(), emit };
+        session.process = new JsonlProcess(cli.command, cli.args, { cwd: thread.cwd }, {
+          onDiagnostic: diagnostic,
+          onExit: error => { for (const pending of session.pendingApprovals.values()) pending.reject(error); session.pendingApprovals.clear(); },
+          onRequest: request => {
+            if (request.method !== 'session/request_permission') throw new Error(`Unsupported ACP client request: ${request.method}`);
+            const requestId = randomUUID();
+            return new Promise((resolve, reject) => {
+              const options = request.params.options || [];
+              session.pendingApprovals.set(requestId, { resolve, reject, options });
+              emit({ kind: 'approval', requestId, method: 'select', title: request.params.toolCall?.title || 'Native tool permission', options: options.map(o => ({ id: o.optionId, label: o.name, kind: o.kind.startsWith('reject') ? 'reject' : undefined })) });
+            });
+          },
+          onEvent: event => {
+            if (event.method === '_x.ai/models/update') { session.state.models = event.params; return; }
+            if (event.method === '_x.ai/session_notification' && event.params.sessionId === session.nativeSessionId) {
+              const u = event.params.update;
+              if (!session.state.loading && u?.usage) { session.state.usage = projectUsage(u.usage); emit({ kind: 'usage', usage: session.state.usage }); }
+              return;
+            }
+            if (event.method !== 'session/update') return;
+            if (session.nativeSessionId && event.params.sessionId !== session.nativeSessionId) return;
+            const u = event.params.update;
+            if (u.sessionUpdate === 'config_option_update') session.state.configOptions = u.configOptions;
+            if (u.sessionUpdate === 'available_commands_update') session.state.commands = u.availableCommands || [];
+            if (u.sessionUpdate === 'current_mode_update' && session.state.modes) session.state.modes.currentModeId = u.currentModeId;
+            if (session.state.loading) return;
+            if (u.sessionUpdate === 'agent_message_chunk') emit({ kind: 'text-delta', text: textOf(u.content) });
+            if (u.sessionUpdate === 'agent_thought_chunk') emit({ kind: 'thinking-delta', text: textOf(u.content) });
+            if (u.sessionUpdate === 'tool_call' || u.sessionUpdate === 'tool_call_update') {
+              const tool = { ...session.tools.get(u.toolCallId), ...u };
+              session.tools.set(u.toolCallId, tool);
+              emit({ kind: 'tool', toolCallId: tool.toolCallId, title: tool.title || tool.kind || 'tool', state: tool.status === 'completed' ? 'completed' : tool.status === 'failed' ? 'error' : 'running', input: tool.rawInput, output: textOf(tool.content) || tool.rawOutput });
+              const changes = (tool.content || []).filter(c => c.type === 'diff').map(c => ({ path: c.path, before: c.oldText ?? '', after: c.newText, changeType: c.oldText == null ? 'added' : 'modified', complete: true }));
+              if (tool.status === 'completed' && changes.length) emit({ kind: 'file-change', source: 'native', changes });
+            }
+            if (u.sessionUpdate === 'plan') emit({ kind: 'plan', entries: u.entries });
+            if (u.sessionUpdate === 'usage_update') {
+              session.state.usage = { tokens: u.used, contextWindow: u.size, ...(u.cost?.currency === 'USD' ? { cost: u.cost.amount } : {}) };
+              emit({ kind: 'usage', usage: session.state.usage });
+            }
+          },
+        });
+        try {
+          const init = await session.process.request('initialize', { protocolVersion: 1, clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false }, clientInfo: { name: 'harness-mix', version: '0.1.0' } });
+          session.state.agentCapabilities = init.agentCapabilities;
+          session.state.commands = init._meta?.availableCommands || [];
+          // L1 会话级注入：Grok 原生协议的 session/new 自带 mcpServers 槽（ACP 形态 stdio 定义）
+          const mcpServers = collaboration ? [{ name: 'harness-mix', command: collaboration.command, args: collaboration.args, env: Object.entries(collaboration.env).map(([envName, value]) => ({ name: envName, value })) }] : [];
+          const result = await session.process.request(thread.restore ? 'session/load' : 'session/new', { cwd: thread.cwd, mcpServers, ...(thread.restore ? { sessionId: thread.nativeSessionId } : {}) });
+          session.nativeSessionId = result.sessionId || thread.nativeSessionId;
+          session.state.configOptions = result.configOptions || result._meta?.['x.ai/sessionConfig']?.options || [];
+          session.state.models = result.models || init._meta?.modelState;
+          session.state.modes = result.modes;
+          session.state.loading = false;
+          const models = catalog(session).models;
+          session.model = models.find(m => m.isDefault) || models[0];
+          if (thread.options?.model) await adapter.setModel(session, thread.options.model);
+          if (thread.options?.thinking) await adapter.setThinkingLevel(session, thread.options.thinking);
+          if (thread.options?.permissionMode) await adapter.setPermissionMode(session, thread.options.permissionMode);
+          emit({ kind: 'session', nativeSessionId: session.nativeSessionId, model: session.model });
+          return session;
+        } catch (error) { session.process.stop(); throw error; }
+      },
+      async describeFor(session) { return catalog(session); },
+      // Grok catalogs and vendor events remain owned by its native stdio process.
+      async listModelsFor(session) { return catalog(session).models; },
+      async send(session, text, hooks, attachments) {
+        const prompt = [...(text ? [{ type: 'text', text }] : []), ...(attachments?.images || []).map(i => ({ type: 'image', data: i.data, mimeType: i.mime }))];
+        const result = await session.process.request('session/prompt', { sessionId: session.nativeSessionId, prompt });
+        if (result._meta?.usage) { session.state.usage = projectUsage(result._meta.usage); hooks.emit({ kind: 'usage', usage: session.state.usage }); }
+        hooks.emit({ kind: 'completed', finalAnswer: result.stopReason !== 'cancelled', nativeRef: { checkpointId: result._meta?.promptId } });
+      },
+      async cancel(session) { session.process.notify('session/cancel', { sessionId: session.nativeSessionId }); },
+      async respond(session, requestId, response) {
+        const pending = session.pendingApprovals.get(requestId);
+        if (!pending) throw new Error('Unknown native approval');
+        const selected = response.optionId ?? response.value;
+        const option = pending.options.find(o => o.optionId === selected);
+        if (!response.cancelled && !option) throw new Error('Select an option offered by Grok');
+        pending.resolve({ outcome: response.cancelled ? { outcome: 'cancelled' } : { outcome: 'selected', optionId: option.optionId } });
+        session.pendingApprovals.delete(requestId);
+      },
+      async setModel(session, model) {
+        const config = session.state.configOptions.find(c => c.category === 'model');
+        if (config) {
+          const result = await session.process.request('session/set_config_option', { sessionId: session.nativeSessionId, configId: config.id, value: model.id });
+          session.state.configOptions = result.configOptions || session.state.configOptions;
+        } else await session.process.request('session/set_model', { sessionId: session.nativeSessionId, modelId: model.id });
+        if (session.state.models) session.state.models.currentModelId = model.id;
+        session.model = model; return model;
+      },
+      async setThinkingLevel(session, level) {
+        if (!catalog(session).thinkingLevels.some(l => l.id === level)) throw new Error('Native reasoning level unavailable');
+        await session.process.request('session/set_mode', { sessionId: session.nativeSessionId, modeId: level });
+      },
+      async setPermissionMode(session, mode) {
+        if (!catalog(session).permissionModes.some(m => m.id === mode)) throw new Error('Native permission mode unavailable');
+        const config = session.state.configOptions.find(c => c.category === 'mode');
+        if (config) {
+          const result = await session.process.request('session/set_config_option', { sessionId: session.nativeSessionId, configId: config.id, value: mode });
+          session.state.configOptions = result.configOptions || session.state.configOptions;
+        } else await session.process.request('session/set_mode', { sessionId: session.nativeSessionId, modeId: mode });
+      },
+      async listCommands(session) { return (session?.state.commands || []).map(c => ({ id: c.name, label: '/' + c.name, description: c.description, action: 'insert' })); },
+      async executeCommand(session, id, hooks) { await adapter.send(session, '/' + id, hooks); },
+      async getContextUsage(session) { return session.state.usage; },
+      async fork(source, context) {
+        if (!fork || context.message) throw new Error('Native ACP does not support this fork boundary');
+        const probe = await adapter.open({ thread: { ...source, restore: true }, emit: () => {}, diagnostic: context.diagnostic });
+        try {
+          const result = await probe.process.request('_x.ai/session/fork', { sourceSessionId: source.nativeSessionId, sourceCwd: source.cwd, newCwd: source.cwd });
+          return { session: await adapter.open({ thread: { ...source, nativeSessionId: result.newSessionId, restore: true }, emit: context.emit, diagnostic: context.diagnostic }) };
+        } finally { await adapter.close(probe); }
+      },
+      async close(session) { session.process.stop(); },
+    };
+    return adapter;
+  }
+  return { manifest, create };
+}
+function projectUsage(u) {
+  const fields = { inputTokens: ['inputTokens', 'input_tokens'], outputTokens: ['outputTokens', 'output_tokens'], reasoningOutputTokens: ['reasoningTokens', 'reasoning_tokens'], cacheRead: ['cachedReadTokens', 'cached_read_tokens'], cacheWrite: ['cacheCreationTokens', 'cache_creation_tokens'] };
+  return Object.fromEntries(Object.entries(fields).flatMap(([key, names]) => { const value = names.map(n => u[n]).find(Number.isFinite); return value === undefined ? [] : [[key, value]]; }));
+}
+module.exports = { ...grokAdapter(), projectUsage };

package/src/main/adapters/hermes.js

@@ -0,0 +1,24 @@
+// Hermes Agent Adapter：`hermes acp`（Nous Research，ACP over stdio）。
+// 实现共享自 ACP 家族工厂（见 acp.js）。能力按官方文档声明面逐项标注：
+// 已文档化：会话持久化/恢复/Fork、流式回答与思考、工具、审批、模型选择。
+// 图片输入：上游 server.py 在 initialize 报告 PromptCapabilities(image=True) 并转发图片块
+// （PR #18030、commit 7e2af0c）；acp.js 在发送时按 initialize 实际值动态防护，旧版本会明确报错而非静默丢弃。
+// 未文档化（不声明）：提问、压缩、Usage。
+const { acpAdapter } = require("./acp");
+
+module.exports = acpAdapter({
+  id: "hermes",
+  name: "Hermes",
+  // Windows 上为 uv/pip 生成的 hermes.exe 启动器；可用 HARNESS_MIX_HERMES_EXECUTABLE 覆盖
+  bin: process.env.HARNESS_MIX_HERMES_EXECUTABLE || "hermes.exe",
+  args: ["acp"],
+  executable: true,
+  images: true,
+  fork: true,
+  thinking: false,
+  permissions: false,
+  questions: false,
+  compaction: false,
+  usage: false,
+  contextUsage: false,
+});

package/src/main/adapters/index.js

@@ -0,0 +1,30 @@
+const pi = require("./pi");
+const dsh = require("./dsh");
+const claude = require("./claude");
+const codex = require("./codex");
+const antigravity = require("./antigravity");
+const opencode = require('./opencode');
+const grok = require('./grok');
+const omp = require('./omp');
+const openclaw = require('./openclaw');
+const hermes = require('./hermes');
+const qoder = require('./qoder');
+const workbuddy = require('./workbuddy');
+const zcode = require('./zcode');
+const trae = require('./trae');
+
+/**
+ * Adapter 注册表（借鉴 codex-host 插件结构：Manifest + 工厂 + Adapter + Session）。
+ * 新增 Harness 时：实现同形状模块并加入此列表，Renderer 无需改动协议。
+ */
+const REGISTRY = [antigravity, pi, omp, dsh, claude, codex, opencode, grok, openclaw, hermes, qoder, workbuddy, zcode, trae];
+
+function buildAdapters(emit) {
+  return REGISTRY.map(({ manifest, create }) => {
+    const adapter = create(emit);
+    adapter.manifest = manifest;
+    return adapter;
+  });
+}
+
+module.exports = { buildAdapters };

package/src/main/adapters/omp.js

@@ -0,0 +1,12 @@
+// OMP（Oh My Pi）Adapter：Pi 的 fork，CLI 与 --mode rpc 协议同源。
+// 实现共享自 Pi 家族工厂（见 pi-family.js）；OMP 侧差异（如有）在此覆盖。
+const { piFamily } = require('./pi-family');
+
+module.exports = piFamily({
+  id: 'omp',
+  name: 'Oh My Pi',
+  icon: 'omp-color.svg',
+  bin: 'omp',
+  packageHint: 'npm i -g @oh-my-pi/pi-coding-agent 或 https://omp.sh/install',
+  aliases: ['omp', 'oh-my-pi'],
+});

package/src/main/adapters/openclaw-gateway.js

@@ -0,0 +1,215 @@
+const { spawn } = require("node:child_process");
+const { promises: fs } = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { cliSpawn } = require("../host/jsonl");
+
+const OPENCLAW_CONFIG = path.join(os.homedir(), ".openclaw", "openclaw.json");
+const DEFAULT_PORT = 18789;
+// 与本机 2026.5.x Gateway 实测协商通过（protocol 4）；范围放宽交给服务端裁决
+const PROTOCOL_MIN = 1;
+const PROTOCOL_MAX = 10;
+const CLIENT_INFO = { id: "gateway-client", version: "0.1.0", mode: "backend" };
+// approvals 事件需要 operator.approvals；模型覆盖（agent 的 model 参数）需要 operator.admin
+const SCOPES = ["operator.read", "operator.write", "operator.approvals", "operator.admin"];
+const CAPS = ["tool-events"];
+
+/**
+ * 读取本机 OpenClaw Gateway 连接参数。
+ * 信任边界：token 只在内存中用于 loopback 握手（与官方 CLI 一致），不持久化、不外发、不写日志。
+ */
+async function readGatewayConfig() {
+  const raw = await fs.readFile(OPENCLAW_CONFIG, "utf8");
+  const cfg = JSON.parse(raw);
+  const auth = cfg?.gateway?.auth ?? {};
+  const token = typeof auth.token === "string" && auth.token ? auth.token : null;
+  if ((auth.mode ?? "token") === "token" && !token) throw new Error("OpenClaw Gateway 为 token 认证但配置中缺少 token");
+  const port = Number.isInteger(cfg?.gateway?.port) ? cfg.gateway.port : DEFAULT_PORT;
+  return { token, port, url: `ws://127.0.0.1:${port}` };
+}
+
+/**
+ * OpenClaw Gateway 共享宿主（协议见 docs.openclaw.ai/gateway/protocol，已按 2026.5.12 实测校准）：
+ * - 帧：{type:'req',id,method,params} → {type:'res',id,ok,payload|error}；广播 {type:'event',event,payload,seq?}。
+ * - 握手：连接后服务端先发 connect.challenge；token 认证直接发 connect（challenge 仅设备签名需要）。
+ * - 惰性拉起：优先连接已运行的 Gateway（每机一个，归用户所有）；未运行才 spawn `openclaw gateway`，
+ *   且仅当子进程由本宿主拉起时才随释放终止。
+ */
+class OpenClawGatewayHost {
+  static #shared = null;
+  static #refs = 0;
+  static #starting = null;
+  static #stopping = null;
+
+  /** 获取共享宿主（必要时连接/拉起）。配对调用 release()。autostart:false 时只连已有 Gateway。 */
+  static async acquire(diagnostic = () => {}, { autostart = true } = {}) {
+    if (OpenClawGatewayHost.#stopping) await OpenClawGatewayHost.#stopping;
+    if (!OpenClawGatewayHost.#shared && !OpenClawGatewayHost.#starting) {
+      OpenClawGatewayHost.#starting = (async () => {
+        const host = new OpenClawGatewayHost(diagnostic);
+        try { await host.#start(autostart); OpenClawGatewayHost.#shared = host; }
+        catch (error) { await host.stop(); throw error; }
+      })().finally(() => { OpenClawGatewayHost.#starting = null; });
+    }
+    if (OpenClawGatewayHost.#starting) await OpenClawGatewayHost.#starting;
+    OpenClawGatewayHost.#refs++;
+    return OpenClawGatewayHost.#shared;
+  }
+
+  static async release() {
+    OpenClawGatewayHost.#refs = Math.max(0, OpenClawGatewayHost.#refs - 1);
+    if (OpenClawGatewayHost.#refs === 0 && OpenClawGatewayHost.#shared) {
+      const host = OpenClawGatewayHost.#shared;
+      OpenClawGatewayHost.#shared = null;
+      const stopping = host.stop();
+      OpenClawGatewayHost.#stopping = stopping;
+      try { await stopping; }
+      finally { if (OpenClawGatewayHost.#stopping === stopping) OpenClawGatewayHost.#stopping = null; }
+    }
+  }
+
+  constructor(diagnostic) {
+    this.diagnostic = diagnostic;
+    this.config = null;      // { token, port, url }
+    this.hello = null;       // hello-ok payload（features/snapshot/policy/auth）
+    this.ws = null;
+    this.rpcSeq = 1;
+    this.pending = new Map(); // id -> { resolve, reject, timer }
+    this.eventListeners = new Set();
+    this.child = null;        // 仅当 Gateway 由本宿主拉起时非空
+  }
+
+  async #start(autostart) {
+    this.config = await readGatewayConfig();
+    try {
+      await this.#connect();
+      return;
+    } catch (error) {
+      if (!autostart) throw error;
+      this.diagnostic(`[openclaw] 未连接到运行中的 Gateway（${error.message}），尝试拉起本地 Gateway`);
+    }
+    await this.#spawnGateway();
+    await this.#connect();
+  }
+
+  /** 拉起本机 Gateway（loopback），等待 WS 就绪。每机只允许一个 Gateway，端口占用时直接复用。 */
+  async #spawnGateway() {
+    const cli = cliSpawn("openclaw", ["gateway"]);
+    const child = spawn(cli.command, cli.args, { windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout.on("data", () => {}); // 持续排空，防止管道写满阻塞
+    child.stderr.on("data", (chunk) => {
+      const line = String(chunk).trim();
+      if (line) this.diagnostic(`[openclaw-gateway] ${line.slice(0, 240)}`);
+    });
+    child.on("exit", () => { if (this.child === child) this.child = null; });
+    this.child = child;
+    const deadline = Date.now() + 90_000;
+    let lastError = null;
+    while (Date.now() < deadline) {
+      try {
+        await this.#connect();
+        return;
+      } catch (error) {
+        lastError = error;
+        if (child.exitCode !== null) break;
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      }
+    }
+    throw new Error(`OpenClaw Gateway 启动后仍无法连接：${lastError?.message ?? "未知错误"}`);
+  }
+
+  /** 建立 WS 并完成 connect 握手（hello-ok）。 */
+  async #connect() {
+    const ws = new WebSocket(this.config.url);
+    this.ws = ws;
+    ws.onmessage = (event) => this.#onFrame(event);
+    ws.onclose = () => this.#onClosed();
+    ws.onerror = () => {};
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error("WebSocket 连接超时")), 10_000);
+      ws.onopen = () => { clearTimeout(timer); resolve(); };
+      ws.onerror = () => { clearTimeout(timer); reject(new Error("WebSocket 连接失败")); };
+    });
+    const hello = await this.call("connect", {
+      minProtocol: PROTOCOL_MIN,
+      maxProtocol: PROTOCOL_MAX,
+      client: { ...CLIENT_INFO, platform: process.platform },
+      role: "operator",
+      scopes: SCOPES,
+      caps: CAPS,
+      commands: [],
+      permissions: {},
+      ...(this.config.token ? { auth: { token: this.config.token } } : {}),
+      locale: "zh-CN",
+    });
+    if (hello?.type !== "hello-ok") throw new Error("Gateway 握手未返回 hello-ok");
+    this.hello = hello;
+    this.diagnostic(`[openclaw] Gateway 已连接（协议 ${hello.protocol}，服务 ${hello.server?.version ?? "unknown"}）`);
+  }
+
+  #onFrame(event) {
+    let msg;
+    try { msg = JSON.parse(event.data); } catch { return; }
+    if (msg.type === "res") {
+      const pending = this.pending.get(msg.id);
+      if (!pending) return;
+      this.pending.delete(msg.id);
+      clearTimeout(pending.timer);
+      if (msg.ok) pending.resolve(msg.payload);
+      else {
+        const error = new Error(msg.error?.message ?? "Gateway 调用失败");
+        error.code = msg.error?.code;
+        pending.reject(error);
+      }
+      return;
+    }
+    if (msg.type === "event") {
+      for (const listener of this.eventListeners) listener(msg);
+    }
+  }
+
+  #onClosed() {
+    const error = new Error("OpenClaw Gateway 连接已断开");
+    for (const pending of this.pending.values()) { clearTimeout(pending.timer); pending.reject(error); }
+    this.pending.clear();
+    for (const listener of this.eventListeners) listener({ type: "closed" });
+  }
+
+  /** 一元 Gateway RPC → payload（业务错误抛出带 code 的 Error）。 */
+  call(method, params = {}, timeoutMs = 30_000) {
+    const id = `hm-${this.rpcSeq++}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${method} 调用超时`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      try { this.ws.send(JSON.stringify({ type: "req", id, method, params })); }
+      catch (error) { clearTimeout(timer); this.pending.delete(id); reject(error); }
+    });
+  }
+
+  /** 订阅广播事件帧（agent / exec.approval.* / closed 等）。 */
+  onEvent(listener) {
+    this.eventListeners.add(listener);
+    return () => this.eventListeners.delete(listener);
+  }
+
+  async stop() {
+    for (const listener of this.eventListeners) listener({ type: "closed" });
+    this.eventListeners.clear();
+    try { this.ws?.close(); } catch { /* 已关闭 */ }
+    this.ws = null;
+    // 仅终止由本宿主拉起的 Gateway；用户自有的 Gateway 服务保持运行
+    const child = this.child;
+    this.child = null;
+    if (child && child.exitCode === null) {
+      try {
+        if (process.platform === "win32") spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { windowsHide: true });
+        else child.kill("SIGTERM");
+      } catch { /* already gone */ }
+    }
+  }
+}
+
+module.exports = { OpenClawGatewayHost, readGatewayConfig, OPENCLAW_CONFIG, DEFAULT_PORT };