@securecoms/agent-bridge 0.7.0 → 0.8.0

package/dist/bin.js

@@ -7047,6 +7047,159 @@ import { join as join9 } from "node:path";
 // src/service/wire.ts
 import { join as join8, dirname as dirname5 } from "node:path";
 import { fileURLToPath } from "node:url";
+
+// src/service/hermes-config.ts
+var HERMES_PLUGIN_NAME = "securecoms-platform";
+function indentOf(line) {
+  const m = line.match(/^( *)/);
+  return m ? m[1].length : 0;
+}
+function isCommentLine(line) {
+  return /^\s*#/.test(line);
+}
+function isBlank(line) {
+  return line.trim() === "";
+}
+function parseKeyLine(line, key) {
+  const m = line.match(new RegExp(`^( *)${key}:(.*)$`));
+  if (!m) return null;
+  const indent = m[1].length;
+  const rest = m[2].trim();
+  if (rest === "" || rest.startsWith("#")) return { idx: -1, indent, inline: null };
+  return { idx: -1, indent, inline: rest };
+}
+function findKeyLine(lines, key, start, end) {
+  for (let i = start; i < end; i++) {
+    const parsed = parseKeyLine(lines[i], key);
+    if (parsed) return { ...parsed, idx: i };
+  }
+  return null;
+}
+function findBlockEnd(lines, start, parentIndent) {
+  let i = start;
+  for (; i < lines.length; i++) {
+    if (isBlank(lines[i])) continue;
+    if (indentOf(lines[i]) > parentIndent) continue;
+    break;
+  }
+  return i;
+}
+function stripQuotesAndComment(raw) {
+  let value = raw.replace(/\s+#.*$/, "").trim();
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if (first === '"' && last === '"' || first === "'" && last === "'") {
+      value = value.slice(1, -1);
+    }
+  }
+  return value;
+}
+function collectItems(lines, start) {
+  const items = [];
+  let i = start;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    if (isCommentLine(line)) {
+      return { items, endIdx: i, ambiguous: true };
+    }
+    const m = line.match(/^( *)-\s*(.+?)\s*$/);
+    if (!m) break;
+    items.push({ idx: i, indent: m[1].length, value: stripQuotesAndComment(m[2]) });
+  }
+  return { items, endIdx: i, ambiguous: false };
+}
+var SIBLING_KEY_RE = /^[\w.-]+:(\s|$)/;
+function isLegitimateListEnd(lines, stopIdx, itemCol, enabledIndent) {
+  if (stopIdx >= lines.length) return true;
+  if (!isBlank(lines[stopIdx])) {
+    return indentOf(lines[stopIdx]) === enabledIndent && SIBLING_KEY_RE.test(lines[stopIdx].trim());
+  }
+  let i = stopIdx;
+  while (i < lines.length && isBlank(lines[i])) i++;
+  if (i >= lines.length) return true;
+  return indentOf(lines[i]) < itemCol;
+}
+function parseInlineList(inline) {
+  const trimmed = inline.trim();
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return [];
+  const inner = trimmed.slice(1, -1).trim();
+  if (inner === "") return [];
+  return inner.split(",").map((s) => stripQuotesAndComment(s.trim()));
+}
+function noop(reason) {
+  return reason ? { action: "noop", reason } : { action: "noop" };
+}
+var MANUAL_INSTRUCTIONS = [
+  "add the following manually under the plugin's config (`~/.hermes/config.yaml`):",
+  "  plugins:",
+  "    enabled:",
+  `      - ${HERMES_PLUGIN_NAME}`
+].join("\n");
+function ensureHermesPluginEnabled(configText) {
+  const eol = configText.includes("\r\n") ? "\r\n" : "\n";
+  const lines = configText.split(/\r\n|\n/);
+  const pluginsIdx = lines.findIndex((l) => /^plugins:\s*(#.*)?$/.test(l));
+  if (pluginsIdx === -1) {
+    return noop(`no \`plugins:\` block found in config.yaml \u2014 ${MANUAL_INSTRUCTIONS}`);
+  }
+  const pluginsIndent = indentOf(lines[pluginsIdx]);
+  const blockEnd = findBlockEnd(lines, pluginsIdx + 1, pluginsIndent);
+  const enabledKey = findKeyLine(lines, "enabled", pluginsIdx + 1, blockEnd);
+  if (!enabledKey) {
+    return noop(`no \`plugins.enabled\` key found in config.yaml \u2014 ${MANUAL_INSTRUCTIONS}`);
+  }
+  if (enabledKey.inline !== null) {
+    return noop(
+      `plugins.enabled uses the inline \`enabled: [...]\` form, which this editor refuses to rewrite (never reformat) \u2014 ${MANUAL_INSTRUCTIONS}`
+    );
+  }
+  const { items, endIdx, ambiguous } = collectItems(lines, enabledKey.idx + 1);
+  if (ambiguous) {
+    return noop(
+      `a comment line interrupts the plugins.enabled list \u2014 refusing rather than guess whether it belongs to the item above or below; ${MANUAL_INSTRUCTIONS}`
+    );
+  }
+  if (items.length === 0) {
+    return noop(`plugins.enabled has no items to copy an indent column from (empty list) \u2014 ${MANUAL_INSTRUCTIONS}`);
+  }
+  const col = items[0].indent;
+  if (items.some((it) => it.indent !== col)) {
+    return noop(`plugins.enabled items are inconsistently indented \u2014 refusing to guess the right column; ${MANUAL_INSTRUCTIONS}`);
+  }
+  const disabledKey = findKeyLine(lines, "disabled", pluginsIdx + 1, blockEnd);
+  let disabledEntries = [];
+  if (disabledKey) {
+    if (disabledKey.inline !== null) {
+      disabledEntries = parseInlineList(disabledKey.inline);
+    } else {
+      disabledEntries = collectItems(lines, disabledKey.idx + 1).items.map((it) => it.value);
+    }
+  }
+  if (disabledEntries.includes(HERMES_PLUGIN_NAME)) {
+    return noop(
+      `${HERMES_PLUGIN_NAME} is listed under plugins.disabled, which wins over plugins.enabled in the Hermes loader \u2014 remove it from plugins.disabled (or move it to plugins.enabled) manually, then re-run wire.`
+    );
+  }
+  if (items.some((it) => it.value === HERMES_PLUGIN_NAME)) {
+    return { action: "noop" };
+  }
+  if (!isLegitimateListEnd(lines, endIdx, col, enabledKey.indent)) {
+    return noop(
+      `plugins.enabled's list doesn't end at a recognized boundary (expected a sibling key, a blank-then-dedent, or end of file) \u2014 refusing to insert at an unverified spot; ${MANUAL_INSTRUCTIONS}`
+    );
+  }
+  const insertLine = `${" ".repeat(col)}- ${HERMES_PLUGIN_NAME}`;
+  const newLines = [...lines.slice(0, endIdx), insertLine, ...lines.slice(endIdx)];
+  return { action: "edited", text: newLines.join(eol) };
+}
+
+// src/service/wire.ts
+var CONNECTOR_FILE_EXTENSIONS = {
+  openclaw: [".js", ".json"],
+  hermes: [".py", ".yaml", ".json"]
+};
+var CONNECTOR_SKIP_DIRS = /* @__PURE__ */ new Set(["tests", "__pycache__"]);
 function detectHarness(home, statDir) {
   if (statDir(`${home}/.openclaw`)) return "openclaw";
   if (statDir(`${home}/.hermes`)) return "hermes";
@@ -7054,11 +7207,41 @@ function detectHarness(home, statDir) {
 }
 function connectorTargetDir(home, harness) {
   if (harness === "openclaw") return `${home}/.openclaw/local-plugins/securecoms`;
-  return `${home}/.hermes/local-plugins/securecoms`;
+  return `${home}/.hermes/plugins/securecoms`;
 }
-function connectorsSrcDir(importMetaUrl) {
+function connectorsSrcDir(importMetaUrl, harness) {
   const pkgRoot = dirname5(dirname5(fileURLToPath(importMetaUrl)));
-  return join8(pkgRoot, "connectors", "openclaw");
+  return join8(pkgRoot, "connectors", harness);
+}
+function hermesConfigPath(home) {
+  return `${home}/.hermes/config.yaml`;
+}
+function hermesConfigBackupPath(configPath, ts, pid) {
+  return `${configPath}.bak-wire-${ts}-${pid}`;
+}
+function enableHermesConfig(home, deps) {
+  const path = hermesConfigPath(home);
+  const text = deps.readHermesConfig(path);
+  if (text === null) {
+    return {
+      ok: false,
+      message: `Hermes config.yaml not found at ${path} (is ~/.hermes installed?) \u2014 add the plugin manually:
+  plugins:
+    enabled:
+      - ${HERMES_PLUGIN_NAME}`
+    };
+  }
+  const result = ensureHermesPluginEnabled(text);
+  if (result.action === "noop") {
+    if (result.reason) return { ok: false, message: result.reason };
+    return { ok: true, message: `${HERMES_PLUGIN_NAME} is already enabled in ${path}.` };
+  }
+  deps.backupHermesConfig(path, text);
+  deps.writeHermesConfig(path, result.text);
+  return {
+    ok: true,
+    message: `enabled ${HERMES_PLUGIN_NAME} in ${path} (the original was backed up alongside it as config.yaml.bak-wire-<ts>-<pid>).`
+  };
 }
 function parseArg(argv, flag) {
   const i = argv.indexOf(flag);
@@ -7086,15 +7269,19 @@ function runWire(deps) {
   const resolved = resolveEntry(deps);
   if (!resolved) return 1;
   const { entry, harness } = resolved;
-  if (harness === "hermes") {
-    deps.log(
-      "[securecoms] Hermes connector is not available yet (fast-follow); detection and target dir only. Nothing installed."
-    );
-    return 1;
-  }
   const targetDir = connectorTargetDir(deps.home, harness);
-  deps.copyConnector(deps.connectorsSrcDir, targetDir);
+  deps.copyConnector(deps.connectorsSrcDir(harness), targetDir, harness);
   deps.writeBinding(targetDir, entry.identityId);
+  if (harness === "hermes") {
+    const enabled = enableHermesConfig(deps.home, deps);
+    deps.log(`[securecoms] ${enabled.message}`);
+    if (!enabled.ok) {
+      deps.log(
+        "wire: Hermes connector files were copied and the binding was written, but the config.yaml plugin entry was NOT enabled automatically \u2014 the harness is NOT wired until you add it manually (see above) and restart the gateway."
+      );
+      return 1;
+    }
+  }
   if (typeof entry.port === "number") {
     const h = deps.getHealth(entry.port);
     if (h && (h.agent_sessions ?? 0) >= 1) {
@@ -7105,17 +7292,23 @@ function runWire(deps) {
   } else {
     deps.log(`wire: connector installed (no bridge port known yet) \u2014 restart the harness to pick it up.`);
   }
+  if (harness === "hermes") {
+    deps.log(
+      "wire: restart the Hermes gateway (`launchctl kickstart -k gui/$UID/ai.hermes.gateway` or your service manager) to pick up the connector."
+    );
+  }
   return 0;
 }
 function runUnwire(deps) {
   const resolved = resolveEntry(deps);
   if (!resolved) return 1;
   const { harness } = resolved;
+  deps.removeBinding(connectorTargetDir(deps.home, harness));
   if (harness === "hermes") {
-    deps.log("[securecoms] Hermes connector is not available yet (fast-follow); nothing to remove.");
-    return 0;
+    deps.log(
+      "[securecoms] Hermes binding removed. The connector files under ~/.hermes/plugins/securecoms and the plugins.enabled entry in config.yaml remain \u2014 removing a listed plugin's files would make Hermes log load errors at boot. Edit config.yaml manually to fully remove it, then restart the gateway."
+    );
   }
-  deps.removeBinding(connectorTargetDir(deps.home, harness));
   return 0;
 }
 
@@ -7132,8 +7325,8 @@ function customFacts(input) {
 function autoWireHarness(input, deps) {
   const h = input.harness;
   if (!h || h === "none") return { echo: "", wired: false, error: false };
-  const retry = `agent-bridge wire --harness openclaw --identity ${input.slug}`;
   if (h === "openclaw") {
+    const retry = `agent-bridge wire --harness openclaw --identity ${input.slug}`;
     const parent = `${input.home}/.openclaw`;
     if (!deps.statDir(parent)) {
       return {
@@ -7147,7 +7340,7 @@ function autoWireHarness(input, deps) {
     const targetDir = connectorTargetDir(input.home, "openclaw");
     try {
       const prev = deps.readBinding(targetDir);
-      deps.copyConnector(input.connectorsSrcDir, targetDir);
+      deps.copyConnector(input.connectorsSrcDir, targetDir, "openclaw");
       deps.writeBinding(targetDir, input.identityId);
       const rebind = prev && prev !== input.identityId ? `
   rebind: ${prev} \u2192 ${input.identityId}` : "";
@@ -7167,8 +7360,48 @@ function autoWireHarness(input, deps) {
     }
   }
   if (h === "hermes") {
-    return { echo: `[securecoms] Hermes turnkey connector is coming (Phase 2). For now drive Hermes via the custom WS path:
-${customFacts(input)}`, wired: false, error: false };
+    const retry = `agent-bridge wire --harness hermes --identity ${input.slug}`;
+    const parent = `${input.home}/.hermes`;
+    if (!deps.statDir(parent)) {
+      return {
+        echo: `[securecoms] Hermes not found at ~/.hermes \u2014 the bridge service is installed, but the harness was NOT wired.
+  Install Hermes, then re-run install, or run: ${retry}
+  (or re-run install with --harness custom).`,
+        wired: false,
+        error: true
+      };
+    }
+    const targetDir = connectorTargetDir(input.home, "hermes");
+    try {
+      const prev = deps.readBinding(targetDir);
+      deps.copyConnector(input.connectorsSrcDir, targetDir, "hermes");
+      deps.writeBinding(targetDir, input.identityId);
+      const enabled = enableHermesConfig(input.home, deps);
+      if (!enabled.ok) {
+        return {
+          echo: `[securecoms] Hermes connector copied and bound to identity ${input.identityId}, but the config.yaml plugin entry was NOT enabled automatically: ${enabled.message}
+  The harness is NOT wired until you add it manually and restart the gateway.`,
+          wired: false,
+          error: true
+        };
+      }
+      const rebind = prev && prev !== input.identityId ? `
+  rebind: ${prev} \u2192 ${input.identityId}` : "";
+      return {
+        echo: `[securecoms] Hermes connector installed and bound to identity ${input.identityId}.${rebind}
+  ${enabled.message}
+  Restart the Hermes gateway (\`launchctl kickstart -k gui/$UID/ai.hermes.gateway\` or your service manager) after install completes.`,
+        wired: true,
+        error: false
+      };
+    } catch (e) {
+      return {
+        echo: `[securecoms] the bridge service is installed, but wiring the Hermes connector FAILED: ${e.message}
+  Retry after fixing the path: ${retry}`,
+        wired: false,
+        error: true
+      };
+    }
   }
   return { echo: `[securecoms] Custom harness \u2014 bring your own connector:
 ${customFacts(input)}`, wired: false, error: false };
@@ -7656,15 +7889,18 @@ function runStatus() {
   else process.stdout.write(renderStatusTable(rows));
   process.exit(0);
 }
-function realCopyConnector(srcDir, dstDir) {
+function realCopyConnector(srcDir, dstDir, harness) {
+  const allowedExt = CONNECTOR_FILE_EXTENSIONS[harness];
   mkdirSync2(dstDir, { recursive: true });
   for (const name of readdirSync(srcDir)) {
     const srcPath = join11(srcDir, name);
     if (statSync2(srcPath).isDirectory()) {
-      realCopyConnector(srcPath, join11(dstDir, name));
+      if (CONNECTOR_SKIP_DIRS.has(name)) continue;
+      realCopyConnector(srcPath, join11(dstDir, name), harness);
       continue;
     }
-    if (!/\.(js|json)$/.test(name)) continue;
+    if (name.includes(".test.")) continue;
+    if (!allowedExt.some((ext) => name.endsWith(ext))) continue;
     writeFileSync3(join11(dstDir, name), readFileSync7(srcPath));
   }
 }
@@ -7690,6 +7926,19 @@ function realStatDir(p) {
     return false;
   }
 }
+function realReadHermesConfig(p) {
+  try {
+    return readFileSync7(p, "utf8");
+  } catch {
+    return null;
+  }
+}
+function realBackupHermesConfig(p, originalText) {
+  writeFileSync3(hermesConfigBackupPath(p, Date.now(), process.pid), originalText, "utf8");
+}
+function realWriteHermesConfig(p, newText) {
+  writeFileSync3(p, newText, "utf8");
+}
 function realWireArgv() {
   if (process.argv.includes("--harness")) return process.argv;
   const detected = detectHarness(homedir2(), realStatDir);
@@ -7706,8 +7955,12 @@ function realWireDeps() {
     getHealth: realGetHealth,
     log: (s) => process.stdout.write(s + "\n"),
     // bin.ts's OWN import.meta.url — see connectorsSrcDir's doc comment in
-    // wire.ts for why it must be the entry point's URL, not wire.ts's.
-    connectorsSrcDir: connectorsSrcDir(import.meta.url)
+    // wire.ts for why it must be the entry point's URL, not wire.ts's. Keyed
+    // by harness (Task 6) so one WireDeps instance can wire either harness.
+    connectorsSrcDir: (h) => connectorsSrcDir(import.meta.url, h),
+    readHermesConfig: realReadHermesConfig,
+    backupHermesConfig: realBackupHermesConfig,
+    writeHermesConfig: realWriteHermesConfig
   };
 }
 function runWireVerb(verb) {
@@ -7736,21 +7989,25 @@ async function runServiceVerb(verb) {
         argOrEnv("--exec-path", "SECURECOMS_EXEC_PATH"),
         realResolveNodeDeps()
       );
+      const installHarness = argOrEnv("--harness", "SECURECOMS_HARNESS");
       const r = await orchestrateInstall({
         credentialAbsPath: credAbs,
         label,
         explicitPort: portStr ? Number(portStr) : void 0,
-        harness: argOrEnv("--harness", "SECURECOMS_HARNESS"),
+        harness: installHarness,
         home: homedir2(),
-        connectorsSrcDir: connectorsSrcDir(import.meta.url),
+        connectorsSrcDir: connectorsSrcDir(import.meta.url, installHarness === "hermes" ? "hermes" : "openclaw"),
         autoWireDeps: {
           statDir: realStatDir,
-          // reuse bin.ts:235
+          // reuse bin.ts:266
           readBinding: realReadBinding,
           copyConnector: realCopyConnector,
-          // bin.ts:212 — one copy impl
+          // bin.ts:225 — one copy impl
           writeBinding: realWriteBinding,
-          // bin.ts:226 — writes {identity_id}
+          // bin.ts:245 — writes {identity_id}
+          readHermesConfig: realReadHermesConfig,
+          backupHermesConfig: realBackupHermesConfig,
+          writeHermesConfig: realWriteHermesConfig,
           log: (s) => process.stderr.write(s + "\n")
         },
         prepDeps: realPrepDeps(),
@@ -7897,6 +8154,7 @@ export {
   chooseInstallExecPath,
   nodeMajorOk,
   parseVerb,
+  realCopyConnector,
   slugFromCredentialPath,
   tokenFingerprint
 };

package/dist/service/harness-wire.d.ts

@@ -1,3 +1,4 @@
+import { type HermesConfigIoDeps, type Harness } from "./wire.js";
 export interface AutoWireInput {
     harness: string | undefined;
     identityId: string;
@@ -7,10 +8,10 @@ export interface AutoWireInput {
     tokenFilePath: string;
     connectorsSrcDir: string;
 }
-export interface AutoWireDeps {
+export interface AutoWireDeps extends HermesConfigIoDeps {
     statDir: (p: string) => boolean;
     readBinding: (dstDir: string) => string | null;
-    copyConnector: (srcDir: string, dstDir: string) => void;
+    copyConnector: (srcDir: string, dstDir: string, harness: Harness) => void;
     writeBinding: (dstDir: string, identityId: string) => void;
     log: (s: string) => void;
 }

package/dist/service/hermes-config.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Strict, line-based editor for `~/.hermes/config.yaml`'s `plugins.enabled`
+ * block sequence. Hermes only loads user plugins listed there (plugins.py's
+ * loader — see spec §4), so `wire --harness hermes` must add our plugin's
+ * entry or the copied connector never runs.
+ *
+ * This module is PURE: it takes the file's text and returns either a noop
+ * (already correct / refused) or the edited text. File I/O and the
+ * `config.yaml.bak-wire-<ts>-<pid>` backup live with the caller (wire.ts /
+ * harness-wire.ts, Task 6).
+ *
+ * Hardened rules (spec §4, audited against the real production file at
+ * `config.yaml:569-573`):
+ *   1. The inserted item copies the EXISTING first item's exact column —
+ *      never `key-indent + 2`. Production shape has items at the SAME
+ *      indent as the `enabled:` key itself (a legal, if unusual, YAML block
+ *      sequence style); some configs indent items by +2. Both must work,
+ *      which is why the column is READ from the first item, never computed.
+ *   2. Insertion lands after the LAST consecutive same-column `- ` item —
+ *      stop scanning at the first line that isn't one (the boundary before
+ *      a sibling key such as `disabled: []`).
+ *   2b. Stopping the scan is not enough on its own: the line the scan
+ *      stopped at must be a LEGITIMATE list terminator before the insertion
+ *      is allowed to happen there. Legitimate means one of: (a) a sibling
+ *      key at the same column as `enabled:` itself (e.g. `disabled:`), (b)
+ *      end-of-block via blank-line(s) then a genuine dedent below the
+ *      items' column, or (c) end of file. Anything else that stops the
+ *      scan — a bare `-`, a mapping-style item (`- ` followed by an
+ *      indented `key: value` on the next line), a blank line followed by
+ *      MORE same-column items (ambiguous: did the writer mean to end the
+ *      list or just add a spacer?), or any other unrecognized content —
+ *      refuses rather than insert at a spot that was never verified to be
+ *      the list's actual end.
+ *   3. `plugins.disabled` is checked too: an entry listed there wins over
+ *      `plugins.enabled` in the loader, so refuse rather than add a second,
+ *      shadowed entry.
+ *   4. Any structural surprise — no `plugins:` block, an inline
+ *      `enabled: [...]` form, an empty enabled list, mixed-indent items, a
+ *      comment line interleaved with items (ambiguous: it could be a
+ *      trailing comment on the item above or a leading comment on the item
+ *      below), or a non-boundary list terminator (see 2b) — refuses with no
+ *      write and an actionable message. Never reformats, never touches any
+ *      other key.
+ */
+export declare const HERMES_PLUGIN_NAME = "securecoms-platform";
+export interface EnsureHermesPluginEnabledResult {
+    action: "noop" | "edited";
+    text?: string;
+    reason?: string;
+}
+export declare function ensureHermesPluginEnabled(configText: string): EnsureHermesPluginEnabledResult;

package/dist/service/wire.d.ts

@@ -1,10 +1,43 @@
 import type { AgentFleetEntry } from "./fleet.js";
 export type Harness = "openclaw" | "hermes";
-export interface WireDeps {
+/**
+ * Per-harness allow-list of file extensions the copier includes when it
+ * installs a connector — openclaw ships a JS runtime, hermes ships Python
+ * (F8: a single `.js|.json` filter silently produced an EMPTY hermes install,
+ * since none of adapter.py/securecoms_transport.py/securecoms_gate.py/
+ * plugin.yaml/__init__.py matched it).
+ */
+export declare const CONNECTOR_FILE_EXTENSIONS: Record<Harness, readonly string[]>;
+/**
+ * Directory names the copier never descends into, checked AT THE DIRECTORY
+ * BRANCH before recursion (F8) — a filename-only extension filter still
+ * walks into `tests/` and would copy every `*.py` it finds there, since `.py`
+ * is itself an allow-listed hermes extension. `__pycache__` is compiled
+ * bytecode, never source, for either harness.
+ */
+export declare const CONNECTOR_SKIP_DIRS: ReadonlySet<string>;
+/** The config read/backup/write seams the Hermes `plugins.enabled` auto-edit
+ *  needs (spec §4, F4). Shared between `WireDeps` (the `wire` verb) and
+ *  `AutoWireDeps` (the `install` auto-wire path) so `enableHermesConfig`
+ *  below is the ONE implementation both paths call — never duplicated,
+ *  never skippable on just one of the two. Unused for the openclaw harness,
+ *  which has no config file to edit. */
+export interface HermesConfigIoDeps {
+    /** Returns null when the file (or its parent ~/.hermes) doesn't exist or
+     *  isn't readable — treated as a config-edit refusal, same posture as any
+     *  other structural surprise `ensureHermesPluginEnabled` reports. */
+    readHermesConfig: (path: string) => string | null;
+    /** Persists the ORIGINAL text under a `hermesConfigBackupPath` name,
+     *  called BEFORE `writeHermesConfig` — only invoked when an edit is about
+     *  to happen, never on a noop/refusal. */
+    backupHermesConfig: (path: string, originalText: string) => void;
+    writeHermesConfig: (path: string, newText: string) => void;
+}
+export interface WireDeps extends HermesConfigIoDeps {
     home: string;
     argv: string[];
     readFleet: () => AgentFleetEntry[];
-    copyConnector: (srcDir: string, dstDir: string) => void;
+    copyConnector: (srcDir: string, dstDir: string, harness: Harness) => void;
     writeBinding: (dstDir: string, identityId: string) => void;
     removeBinding: (dstDir: string) => void;
     getHealth: (port: number) => {
@@ -12,20 +45,17 @@ export interface WireDeps {
     } | null;
     log: (s: string) => void;
     /**
-     * Precomputed absolute path to the reference connector's source dir
-     * (`<pkgRoot>/connectors/openclaw`). REQUIRED: the only real caller
-     * (bin.ts's realWireDeps) always computes this via
-     * `connectorsSrcDir(import.meta.url)` using bin.ts's OWN import.meta.url —
-     * see that function's doc comment for why it has to be bin.ts's URL, not
-     * wire.ts's. A fallback that read wire.ts's own import.meta.url used to
-     * live here, but wire.ts sits one directory deeper than bin.ts
-     * (`src/service/wire.ts` vs `src/bin.ts`), so that fallback resolved to
-     * the wrong path — removed rather than fixed, since every real caller
-     * already supplies this field. Unit tests must pass a value too (any
-     * string is fine — `copyConnector` is mocked in tests and never inspects
-     * it for the non-hermes paths that reach it).
+     * Resolves a harness's connector SOURCE dir on demand, keyed by harness —
+     * Task 6 makes BOTH openclaw and hermes real installs, so a single
+     * WireDeps instance must be able to wire either one. Real callers
+     * (bin.ts's realWireDeps) supply `(h) => connectorsSrcDir(import.meta.url,
+     * h)` using bin.ts's OWN import.meta.url — see the standalone
+     * `connectorsSrcDir` function's doc comment below for why it has to be the
+     * entry point's URL, not wire.ts's own. Unit tests must pass a function
+     * too (any string-returning stub is fine — `copyConnector` is mocked in
+     * tests and never inspects the path for its own sake).
      */
-    connectorsSrcDir: string;
+    connectorsSrcDir: (harness: Harness) => string;
 }
 /**
  * Detects an installed harness by probing well-known home-relative dirs.
@@ -35,42 +65,69 @@ export interface WireDeps {
  */
 export declare function detectHarness(home: string, statDir: (p: string) => boolean): Harness | null;
 /**
- * Where the connector gets installed for a given harness. Openclaw is the
- * REFERENCE CONNECTOR (Task 6, connectors/openclaw/) and is fully wired.
- * Hermes gets a defined target path so `detectHarness`/`wire --harness hermes`
- * don't crash, but the Hermes CONNECTOR ITSELF is a fast-follow — only
- * detection + this target dir ship in this task. Do not claim a working
- * Hermes connector exists.
+ * Where the connector gets installed for a given harness. Both harnesses are
+ * real installs as of Task 6: openclaw at its `local-plugins` dir; hermes at
+ * `~/.hermes/plugins/securecoms` — the loader's actual user-plugins dir
+ * (verified against the production config; `local-plugins` was a Task 4/5
+ * placeholder value, never the real one).
  */
 export declare function connectorTargetDir(home: string, harness: Harness): string;
 /**
- * Resolves the reference connector's SOURCE dir at runtime. `connectors/` is
- * shipped SOURCE (not compiled — H2), so this must resolve from the running
- * file's location back to the package root, never into dist/. Callers pass
- * their OWN import.meta.url (bin.ts's), not wire.ts's: esbuild bundles
- * wire.ts's code into dist/bin.js, so only the entry point's import.meta.url
- * is guaranteed to sit exactly one directory below the package root in BOTH
- * dev (src/bin.ts) and the built artifact (dist/bin.js) — mirrors
- * resolve-bin.ts's loadPackageMeta (`dist/bin.js -> ../package.json`).
+ * Resolves a connector's SOURCE dir at runtime, keyed by harness (`connectors/
+ * <harness>`) — `connectors/` is shipped SOURCE (not compiled — H2), so this
+ * must resolve from the running file's location back to the package root,
+ * never into dist/. Callers pass their OWN import.meta.url (bin.ts's), not
+ * wire.ts's: esbuild bundles wire.ts's code into dist/bin.js, so only the
+ * entry point's import.meta.url is guaranteed to sit exactly one directory
+ * below the package root in BOTH dev (src/bin.ts) and the built artifact
+ * (dist/bin.js) — mirrors resolve-bin.ts's loadPackageMeta (`dist/bin.js ->
+ * ../package.json`).
+ */
+export declare function connectorsSrcDir(importMetaUrl: string, harness: Harness): string;
+/** Path to the Hermes gateway's `config.yaml`, whose `plugins.enabled` block
+ *  the auto-edit targets (spec §4). v1 targets the default `~/.hermes`
+ *  profile only — `HERMES_HOME`/secondary profiles are documented as
+ *  unsupported by `wire` in this round (spec §4 scope limit). */
+export declare function hermesConfigPath(home: string): string;
+/** Backup filename for a config.yaml auto-edit: `<path>.bak-wire-<ts>-<pid>`
+ *  (spec §4 rule 4) — unique enough per host that two `wire` runs essentially
+ *  never collide (different timestamp, or different pid at the same ms). */
+export declare function hermesConfigBackupPath(configPath: string, ts: number, pid: number): string;
+/**
+ * F4 (load-bearing): the ONE enable helper invoked from BOTH `runWire` (the
+ * `wire` verb, below) and `autoWireHarness` (the `install` auto-wire path,
+ * harness-wire.ts) — a hermes wire that copies the connector and writes the
+ * binding but skips this step is the silent half-wire the spec forbids.
+ * Reads config.yaml, runs Task 5's pure `ensureHermesPluginEnabled`, and on
+ * an actual edit backs up the ORIGINAL text before writing the new text.
+ * Never writes anything on a noop or a refusal.
  */
-export declare function connectorsSrcDir(importMetaUrl: string): string;
+export declare function enableHermesConfig(home: string, deps: HermesConfigIoDeps): {
+    ok: boolean;
+    message: string;
+};
 /**
  * Installs the reference connector into the harness's plugin dir and drops
  * an explicit securecoms.binding.json naming the resolved agent's identity.
  * There is NO auto-discovery (audit C1): the binding is written for EVERY
  * agent, singleton included, every time `wire` runs.
  *
- * Hermes has no real connector yet (this round only ships detection +
- * `connectorTargetDir`, see that function's doc comment) — refuse rather
- * than install the openclaw connector's files into a Hermes plugin dir,
- * which would be a false "installed" success.
+ * Hermes (Task 6) additionally needs its `~/.hermes/config.yaml`
+ * `plugins.enabled` entry (F4's `enableHermesConfig`, shared with
+ * autoWireHarness) — Hermes only loads plugins listed there, so the copy +
+ * binding alone would leave the connector inert. If that edit refuses (no
+ * `plugins:` block, an already-disabled entry, an ambiguous list shape, or a
+ * missing config.yaml entirely), the copy and binding REMAIN on disk — they
+ * are harmless without the enable — but `wire` exits non-zero with the
+ * manual-edit instructions, so callers see harness-NOT-wired rather than a
+ * silent half-wire.
  */
 export declare function runWire(deps: WireDeps): number;
 /** Removes the explicit binding for the resolved agent. Leaves the copied
- *  connector files in place — unwire un-names the agent, it doesn't uninstall
- *  the plugin (that stays a harness-native operation).
- *
- *  Hermes never has anything installed by `runWire` (see its hermes guard),
- *  so there's nothing to remove — no-op cleanly rather than call
- *  `removeBinding` against a dir that was never created. */
+ *  connector files (and, for hermes, the config.yaml plugin entry) in place
+ *  — unwire un-names the agent, it doesn't uninstall the plugin (that stays
+ *  a harness-native operation). For hermes specifically: removing the
+ *  installed files while config.yaml still lists the plugin would make
+ *  Hermes log load errors at boot, so the copy AND the config entry both
+ *  deliberately remain — printed as explicit manual-cleanup instructions. */
 export declare function runUnwire(deps: WireDeps): number;