agent-comm-hub 0.2.0 → 0.4.0

package/lib/cli.js

@@ -3,6 +3,417 @@
 // src/index.ts
 import { createServer } from "node:http";
 
+// src/herdr-ctl.ts
+import { execFile } from "node:child_process";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+var AGENT_STATUSES = ["idle", "working", "blocked", "done", "unknown"];
+var HerdrCtl = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.bin = options.bin ?? "herdr";
+    this.baseArgs = options.baseArgs ?? [];
+    this.defaultTimeoutMs = options.defaultTimeoutMs ?? 3e4;
+    this.socketPath = options.socketPath ?? defaultSocketPath();
+    this.sendRequest = options.sendRequest ?? ((method, params) => socketSend(this.socketPath, method, params));
+  }
+  bin;
+  baseArgs;
+  defaultTimeoutMs;
+  sendRequest;
+  socketPath;
+  // ---- pane-level control (socket API; works for ANY pane, no agent
+  // detection required — this is the channel that drives agents herdr does
+  // not recognize, e.g. MiniMax Code) --------------------------------
+  /** `pane.list` — every pane in the session (ids, titles, agent states). */
+  async paneList() {
+    const result = await this.sendRequest("pane.list", {});
+    const raw = result.panes;
+    if (!Array.isArray(raw)) throw new Error(`herdr pane.list: unexpected result shape: ${JSON.stringify(result)}`);
+    return raw.map((item) => toPane(item));
+  }
+  /** `pane.send_input` — type text into a pane's input (physical input; the
+   * pane's program receives it as keystrokes). */
+  async paneSendText(paneId, text) {
+    if (text === "") throw new Error("paneSendText: text must not be empty");
+    await this.sendRequest("pane.send_input", { pane_id: paneId, text });
+  }
+  /** `pane.send_keys` — raw key presses (Enter, esc, ctrl-c, ...). */
+  async paneSendKeys(paneId, keys) {
+    if (keys.length === 0) throw new Error("paneSendKeys: at least one key is required");
+    await this.sendRequest("pane.send_keys", { pane_id: paneId, keys });
+  }
+  /** `pane.read` — recent terminal output of a pane. */
+  async paneRead(paneId, options = {}) {
+    const params = { pane_id: paneId, source: options.source ?? "recent", format: "text", strip_ansi: true };
+    if (options.lines !== void 0) params.lines = options.lines;
+    const result = await this.sendRequest("pane.read", params);
+    const raw = result.read ?? result;
+    const read = raw;
+    return {
+      paneId: String(read.pane_id ?? paneId),
+      tabId: read.tab_id === void 0 ? "" : String(read.tab_id),
+      workspaceId: read.workspace_id === void 0 ? null : String(read.workspace_id),
+      source: String(read.source ?? options.source ?? "recent"),
+      text: String(read.text ?? ""),
+      revision: Number(read.revision ?? 0),
+      truncated: read.truncated === true
+    };
+  }
+  /** `pane.wait_for_output` — block until the pane output matches a pattern
+   * (substring or regex), or the budget elapses. Returns the matched pane
+   * output, or null on timeout. */
+  async paneWaitForOutput(paneId, match, options = {}) {
+    const params = {
+      pane_id: paneId,
+      source: options.source ?? "recent",
+      match: { type: match.type, value: match.value },
+      strip_ansi: true
+    };
+    if (options.lines !== void 0) params.lines = options.lines;
+    if (options.timeoutMs !== void 0) params.timeout_ms = options.timeoutMs;
+    let result;
+    try {
+      result = await this.sendRequest("pane.wait_for_output", params);
+    } catch (error) {
+      if (/(timeout|timed out)/i.test(error.message)) return null;
+      throw error;
+    }
+    const raw = result.read ?? result;
+    if (raw === null || typeof raw !== "object") return null;
+    const read = raw;
+    return {
+      paneId: String(read.pane_id ?? paneId),
+      tabId: read.tab_id === void 0 ? "" : String(read.tab_id),
+      workspaceId: read.workspace_id === void 0 ? null : String(read.workspace_id),
+      source: String(read.source ?? options.source ?? "recent"),
+      text: String(read.text ?? ""),
+      revision: Number(read.revision ?? 0),
+      truncated: read.truncated === true
+    };
+  }
+  // ---- smart control: use herdr's agent features when the target is
+  // recognized, transparently fall back to pane-level control otherwise ---
+  /** Detect whether herdr recognizes `target` as an agent (i.e. its
+   * agent.get succeeds). Unrecognized panes fall back to pane control. */
+  async detectTarget(target) {
+    try {
+      await this.get(target);
+      return "agent";
+    } catch {
+      return "pane";
+    }
+  }
+  /** Prompt with automatic fallback: agent.prompt for recognized agents
+   * (state-machine wait), pane.send_input + output-settling wait otherwise. */
+  async promptSmart(target, text, options = {}) {
+    if (await this.detectTarget(target) === "agent") {
+      const settled2 = await this.prompt(target, text, {
+        wait: options.wait,
+        until: options.until,
+        timeoutMs: options.timeoutMs
+      });
+      return { via: "agent", settled: settled2 };
+    }
+    await this.paneSendText(target, text);
+    if (options.enter !== false) await this.paneSendKeys(target, ["Enter"]);
+    if (options.wait !== true) return { via: "pane", settled: null };
+    const budget = options.timeoutMs ?? this.defaultTimeoutMs;
+    const settled = await this.waitForPaneSettled(target, budget);
+    return { via: "pane", settled };
+  }
+  /** Wait with automatic fallback: agent.wait (state machine) for recognized
+   * agents; pane output-settling heuristic otherwise. */
+  async waitSmart(target, options = {}) {
+    if (await this.detectTarget(target) === "agent") {
+      const settled2 = await this.wait(target, options);
+      return { via: "agent", settled: settled2 };
+    }
+    const budget = options.timeoutMs ?? this.defaultTimeoutMs;
+    const settled = await this.waitForPaneSettled(target, budget);
+    return { via: "pane", settled };
+  }
+  /** Read terminal output of a target. Uses the socket `pane.read` for both
+   * recognized agents and plain panes: the CLI's `agent read --format text`
+   * prints RAW text to stdout (no JSON envelope), so it cannot feed the
+   * structured result path — the socket request is uniform and carries
+   * revision/truncated metadata. */
+  async readSmart(target, options = {}) {
+    return this.paneRead(target, options);
+  }
+  /** Key presses with automatic fallback: agent.send_keys for recognized
+   * agents, pane.send_keys otherwise. */
+  async keysSmart(target, keys) {
+    if (keys.length === 0) throw new Error("keysSmart: at least one key is required");
+    if (await this.detectTarget(target) === "agent") {
+      await this.sendKeys(target, keys);
+      return;
+    }
+    await this.paneSendKeys(target, keys);
+  }
+  /** Status with automatic fallback: agent.get for recognized agents; a
+   * pane-derived summary (status unknown) otherwise. */
+  async statusSmart(target) {
+    try {
+      const agent = await this.get(target);
+      return { agent, pane: null };
+    } catch {
+      try {
+        const panes = await this.paneList();
+        const pane = panes.find((p) => p.paneId === target);
+        return { agent: null, pane: pane ?? null };
+      } catch {
+        return { agent: null, pane: null };
+      }
+    }
+  }
+  /** Heuristic settle for unrecognized panes: poll pane.read revisions until
+   * the output stops changing for a short window, or the budget elapses. */
+  async waitForPaneSettled(paneId, timeoutMs) {
+    const startedAt = Date.now();
+    let lastRevision = -1;
+    let stableTicks = 0;
+    const stableTarget = 2;
+    const pollMs = 1500;
+    for (; ; ) {
+      const elapsed = Date.now() - startedAt;
+      if (elapsed >= timeoutMs) return null;
+      try {
+        const read = await this.paneRead(paneId, { source: "recent" });
+        if (read.revision === lastRevision) {
+          stableTicks++;
+          if (stableTicks >= stableTarget) {
+            return { paneId, status: "idle", waitedMs: Date.now() - startedAt };
+          }
+        } else {
+          stableTicks = 0;
+          lastRevision = read.revision;
+        }
+      } catch {
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+  }
+  // ---- agent-level control (CLI; requires herdr to recognize the agent) ---
+  /** `herdr agent list` — every agent pane herdr currently detects. */
+  async list() {
+    const result = await this.run(["agent", "list"]);
+    const raw = result.agents;
+    if (!Array.isArray(raw)) throw new Error(`herdr agent list: unexpected result shape: ${JSON.stringify(result)}`);
+    return raw.map((item) => toAgent(item));
+  }
+  /** `herdr agent get <target>` — one agent pane (by paneId or name). */
+  async get(target) {
+    const result = await this.run(["agent", "get", target]);
+    const raw = result.agent;
+    if (raw === void 0 || raw === null) throw new Error(`herdr agent get: unexpected result shape: ${JSON.stringify(result)}`);
+    return toAgent(raw);
+  }
+  /** `herdr agent read <target>` — recent terminal output of the pane. */
+  async read(target, options = {}) {
+    const args = ["agent", "read", target];
+    if (options.source !== void 0) args.push("--source", options.source);
+    if (options.lines !== void 0) args.push("--lines", String(options.lines));
+    args.push("--format", "text");
+    const result = await this.run(args);
+    const raw = result.read ?? result;
+    const read = raw;
+    return {
+      paneId: String(read.pane_id ?? target),
+      tabId: read.tab_id === void 0 ? "" : String(read.tab_id),
+      workspaceId: read.workspace_id === void 0 ? null : String(read.workspace_id),
+      source: String(read.source ?? options.source ?? "recent"),
+      text: String(read.text ?? ""),
+      revision: Number(read.revision ?? 0),
+      truncated: read.truncated === true
+    };
+  }
+  /** `herdr agent send-keys <target> <KEY>...` — raw key presses (Enter,
+   * esc, ctrl-c, arrows; named keys are passed through to herdr). */
+  async sendKeys(target, keys) {
+    if (keys.length === 0) throw new Error("sendKeys: at least one key is required");
+    await this.run(["agent", "send-keys", target, ...keys]);
+  }
+  /** `herdr agent prompt <target> <text>` — submit text to the agent's
+   * input line (a slash command like `/compact` is executed by the agent's
+   * TUI, not treated as chat content). With `wait`, blocks until the agent
+   * settles (default idle/done/blocked, or the exact `until` states) or
+   * `timeoutMs` elapses. */
+  async prompt(target, text, options = {}) {
+    const args = ["agent", "prompt", target, text];
+    if (options.wait === true) args.push("--wait");
+    for (const status of options.until ?? []) args.push("--until", status);
+    if (options.timeoutMs !== void 0) args.push("--timeout", String(options.timeoutMs));
+    const result = await this.run(args, options.timeoutMs);
+    return settleFrom(result, target);
+  }
+  /** `herdr agent wait <target>` — block until the agent reaches one of the
+   * requested states (default idle/done/blocked) or `timeoutMs` elapses. */
+  async wait(target, options = {}) {
+    const args = ["agent", "wait", target];
+    for (const status of options.until ?? []) args.push("--until", status);
+    if (options.timeoutMs !== void 0) args.push("--timeout", String(options.timeoutMs));
+    const result = await this.run(args, options.timeoutMs);
+    return settleFrom(result, target);
+  }
+  /** Run one herdr CLI invocation and parse its JSON envelope. */
+  run(args, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      execFile(
+        this.bin,
+        [...this.baseArgs, ...args],
+        { timeout: timeoutMs ?? this.defaultTimeoutMs, windowsHide: true, maxBuffer: 16 * 1024 * 1024 },
+        (error, stdout, stderr) => {
+          if (error) {
+            const err = error;
+            if (err.code === "ENOENT") {
+              reject(new Error(`herdr CLI not found ('${this.bin}') \u2014 install herdr (https://herdr.dev) or point --herdr-bin at it`));
+              return;
+            }
+            const payload = stdout || stderr || "";
+            let envelope = null;
+            try {
+              envelope = JSON.parse(payload);
+            } catch {
+            }
+            if (envelope !== null && typeof envelope === "object" && envelope.error !== void 0) {
+              reject(new Error(`${envelope.error.code ?? "herdr error"}: ${envelope.error.message ?? "unknown error"}`));
+              return;
+            }
+            const hint = payload.trim() !== "" ? ` \u2014 ${payload.trim().slice(0, 200)}` : "";
+            reject(new Error(`herdr ${args.slice(0, 2).join(" ")} failed${hint}`));
+            return;
+          }
+          let parsed = null;
+          try {
+            parsed = JSON.parse(stdout);
+          } catch {
+          }
+          if (parsed === null || typeof parsed !== "object") {
+            reject(new Error(`herdr returned non-JSON output: ${stdout.slice(0, 200)}`));
+            return;
+          }
+          if (parsed.error !== void 0) {
+            reject(new Error(`${parsed.error.code ?? "herdr error"}: ${parsed.error.message ?? "unknown error"}`));
+            return;
+          }
+          resolve(parsed.result);
+        }
+      );
+    });
+  }
+};
+function toAgent(raw) {
+  const status = raw.agent_status;
+  return {
+    paneId: String(raw.pane_id ?? ""),
+    tabId: raw.tab_id === void 0 ? "" : String(raw.tab_id),
+    terminalId: raw.terminal_id === void 0 ? "" : String(raw.terminal_id),
+    name: raw.name === void 0 ? null : String(raw.name),
+    agent: raw.agent === void 0 ? null : String(raw.agent),
+    displayAgent: raw.display_agent === void 0 ? null : String(raw.display_agent),
+    status: AGENT_STATUSES.includes(status) ? status : "unknown",
+    cwd: raw.cwd === void 0 ? null : String(raw.cwd),
+    focused: raw.focused === true,
+    interactiveReady: raw.interactive_ready === true,
+    launchPending: raw.launch_pending === true,
+    terminalTitle: raw.terminal_title === void 0 ? null : String(raw.terminal_title),
+    revision: Number(raw.revision ?? 0)
+  };
+}
+function settleFrom(result, target) {
+  if (result === null || typeof result !== "object") return null;
+  const obj = result;
+  const event = obj.event;
+  const status = event?.agent_status ?? obj.agent_status ?? obj.status;
+  if (AGENT_STATUSES.includes(status)) {
+    return {
+      paneId: String(event?.pane_id ?? obj.pane_id ?? target),
+      status,
+      waitedMs: Number(obj.waited_ms ?? null) || null
+    };
+  }
+  return null;
+}
+function toPane(raw) {
+  const status = raw.agent_status;
+  return {
+    paneId: String(raw.pane_id ?? ""),
+    tabId: raw.tab_id === void 0 ? "" : String(raw.tab_id),
+    workspaceId: raw.workspace_id === void 0 ? "" : String(raw.workspace_id),
+    terminalId: raw.terminal_id === void 0 ? "" : String(raw.terminal_id),
+    title: raw.terminal_title_stripped === void 0 ? null : String(raw.terminal_title_stripped),
+    agentStatus: AGENT_STATUSES.includes(status) ? status : "unknown",
+    cwd: raw.cwd === void 0 ? null : String(raw.cwd),
+    focused: raw.focused === true,
+    revision: Number(raw.revision ?? 0)
+  };
+}
+function defaultSocketPath() {
+  if (process.platform === "win32") {
+    const base = process.env.APPDATA ?? process.env.USERPROFILE ?? ".";
+    return `\\\\.\\pipe\\${path.join(base, "herdr", "herdr.sock")}`;
+  }
+  return path.join(os.homedir(), ".config", "herdr", "herdr.sock");
+}
+function socketSend(socketPath, method, params) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    let buffer = "";
+    let settled = false;
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      reject(error);
+    };
+    const timeout = setTimeout(() => fail(new Error(`herdr socket request timed out: ${method}`)), 15e3);
+    socket.on("connect", () => {
+      socket.write(JSON.stringify({ id: `dsh-${Date.now()}`, method, params }) + "\n");
+    });
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.trim() === "") continue;
+        let envelope;
+        try {
+          envelope = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (settled) continue;
+        settled = true;
+        clearTimeout(timeout);
+        socket.destroy();
+        if (envelope.error !== void 0) {
+          reject(new Error(`${envelope.error.code ?? "herdr error"}: ${envelope.error.message ?? "unknown error"}`));
+        } else {
+          resolve(envelope.result);
+        }
+      }
+    });
+    socket.on("error", (error) => fail(error));
+    socket.on("close", () => {
+      if (!settled && buffer.trim() !== "") {
+        try {
+          const envelope = JSON.parse(buffer);
+          settled = true;
+          clearTimeout(timeout);
+          if (envelope.error !== void 0) reject(new Error(`${envelope.error.code ?? "herdr error"}: ${envelope.error.message ?? "unknown error"}`));
+          else resolve(envelope.result);
+        } catch {
+          fail(new Error(`herdr socket closed without a response: ${method}`));
+        }
+      } else if (!settled) {
+        fail(new Error(`herdr socket closed without a response: ${method}`));
+      }
+    });
+  });
+}
+
 // src/hub.ts
 import { randomUUID } from "node:crypto";
 
@@ -291,6 +702,22 @@ function hubTools(hub, registry, options) {
     ts: message.ts
   });
   const presentWait = (result) => result.type === "timeout" ? result : { type: "message", message: present(result.message) };
+  const checkControl = (peer) => {
+    const herdr = options.herdr;
+    if (herdr === void 0) {
+      throw new Error("herdr control not enabled \u2014 start the hub with --herdr-bin or pass a herdrCtl to hubTools");
+    }
+    const control = options.herdrControlPeers ?? "all";
+    if (control !== "all" && !control.has(peer)) {
+      throw new Error(`peer '${peer}' is not allowed to use bridge_agent_* tools`);
+    }
+    return herdr;
+  };
+  const asStatuses = (value) => {
+    if (!Array.isArray(value)) return void 0;
+    const statuses = value.map(String).filter((status) => AGENT_STATUSES.includes(status));
+    return statuses.length > 0 ? statuses : void 0;
+  };
   const wrap = (peerAware, handler) => async (args, sessionId) => {
     const peer = peerAware ? requirePeer(sessionId) : "";
     return handler(args, peer, sessionId);
@@ -416,6 +843,203 @@ function hubTools(hub, registry, options) {
       description: "Recent messages involving you (newest first); pass `peer` to inspect another peer's conversation. Use to refresh context after a reconnect.",
       inputSchema: schema({ peer: optStr("PeerId whose conversation to inspect; default: yourself."), limit: int("How many messages to return (default 20).") }),
       handler: wrap(true, async (args, peer) => ({ messages: hub.history(args.peer === void 0 ? peer : String(args.peer), Math.min(args.limit === void 0 ? 20 : Number(args.limit), 100)).map(present) }))
+    },
+    // ---- herdr control tools ------------------------------------------
+    // These type into real agent terminals via the herdr runtime. They are
+    // gated by checkControl and documented as physical input: unlike
+    // bridge_chat (a mailbox message the model may ignore), a prompt here is
+    // executed by the target's TUI — slash commands included.
+    {
+      name: "bridge_agent_list",
+      description: "List agent panes detected by the herdr terminal runtime (paneId, agent kind, lifecycle status, cwd, interactive-ready). Use a paneId as the `target` of the other bridge_agent_* tools. Control tools: they type into the target terminal \u2014 use with care.",
+      inputSchema: schema({}),
+      handler: wrap(true, async (_args, peer) => ({ agents: await checkControl(peer).list() }))
+    },
+    {
+      name: "bridge_agent_status",
+      description: 'Live status of a target: for agents herdr recognizes, the full lifecycle state (idle/working/blocked/done) and agent kind; for unrecognized panes, a pane-derived summary with status "unknown" and `pane` populated. `target` is a herdr paneId from bridge_pane_list / bridge_agent_list.',
+      inputSchema: schema({ target: str("herdr paneId, e.g. w1:p1, from bridge_agent_list or bridge_pane_list.") }, ["target"]),
+      handler: wrap(true, async (args, peer) => {
+        const result = await checkControl(peer).statusSmart(String(args.target));
+        return { agent: result.agent, ...result.pane !== null ? { pane: result.pane } : {} };
+      })
+    },
+    {
+      name: "bridge_agent_prompt",
+      description: 'Submit text directly into the target terminal. For agents herdr recognizes, uses agent.prompt \u2014 a state-machine wait (`wait: true` blocks until idle/done/blocked, exact states via `until`). For unrecognized panes (e.g. MiniMax Code), falls back to pane-level input (`pane.send_input`) and waits for the pane output to settle. Slash commands are executed by the target\'s TUI either way. Returns `via: "agent" | "pane"` so callers know which channel was used.',
+      inputSchema: schema(
+        {
+          target: str("herdr paneId, e.g. w1:p1, from bridge_pane_list / bridge_agent_list."),
+          text: str("Text to submit (slash commands are executed, not sent as chat)."),
+          wait: { type: "boolean", description: "Wait for the agent to settle after submission (default false)." },
+          until: { type: "array", items: { type: "string", enum: [...AGENT_STATUSES] }, description: "Exact states to wait for (agent channel; default: idle/done/blocked)." },
+          timeoutMs: int("Wait cap in ms (default 30000).")
+        },
+        ["target", "text"]
+      ),
+      handler: wrap(true, async (args, peer) => {
+        const ctl = checkControl(peer);
+        const waiting = args.wait === true;
+        const result = await ctl.promptSmart(String(args.target), String(args.text), {
+          wait: waiting,
+          until: asStatuses(args.until),
+          timeoutMs: args.timeoutMs === void 0 ? void 0 : Number(args.timeoutMs)
+        });
+        return waiting ? { submitted: true, via: result.via, settled: result.settled } : { submitted: true, via: result.via };
+      })
+    },
+    {
+      name: "bridge_agent_wait",
+      description: 'Wait until the target settles. For agents herdr recognizes: state-machine wait (agent.wait \u2014 idle/working/blocked/done, `until` for exact states). For unrecognized panes: falls back to polling pane output until it stops changing. Returns `via: "agent" | "pane"`; a `settled: null` result means the timeout fired first.',
+      inputSchema: schema(
+        {
+          target: str("herdr paneId, e.g. w1:p1, from bridge_pane_list / bridge_agent_list."),
+          until: { type: "array", items: { type: "string", enum: [...AGENT_STATUSES] }, description: "Exact states to wait for (agent channel; default: idle/done/blocked)." },
+          timeoutMs: int("Wait cap in ms (default 30000).")
+        },
+        ["target"]
+      ),
+      handler: wrap(true, async (args, peer) => {
+        const result = await checkControl(peer).waitSmart(String(args.target), {
+          until: asStatuses(args.until),
+          timeoutMs: args.timeoutMs === void 0 ? void 0 : Number(args.timeoutMs)
+        });
+        return { via: result.via, settled: result.settled };
+      })
+    },
+    {
+      name: "bridge_agent_read",
+      description: "Read the target's recent terminal output (plain text). Uses agent.read for recognized agents, pane.read otherwise. Use to collect the reply of an agent that is not connected to the hub (its output never enters a mailbox).",
+      inputSchema: schema(
+        {
+          target: str("herdr paneId, e.g. w1:p1, from bridge_pane_list / bridge_agent_list."),
+          lines: int("How many lines to read (default: all recent)."),
+          source: { type: "string", enum: ["visible", "recent", "recent-unwrapped", "detection"], description: "Terminal snapshot source (default recent)." }
+        },
+        ["target"]
+      ),
+      handler: wrap(
+        true,
+        async (args, peer) => checkControl(peer).readSmart(String(args.target), {
+          lines: args.lines === void 0 ? void 0 : Number(args.lines),
+          source: args.source === void 0 ? void 0 : args.source
+        })
+      )
+    },
+    {
+      name: "bridge_agent_keys",
+      description: "Send raw key presses to the target terminal \u2014 Enter, esc, ctrl-c, arrows, etc. Use to dismiss permission prompts or interrupt a stuck agent. Keys are passed verbatim.",
+      inputSchema: schema(
+        {
+          target: str("herdr paneId, e.g. w1:p1, from bridge_pane_list / bridge_agent_list."),
+          keys: { type: "array", items: { type: "string" }, description: 'Keys to send, e.g. ["Enter"], ["esc"], ["ctrl-c", "Enter"].' }
+        },
+        ["target", "keys"]
+      ),
+      handler: wrap(true, async (args, peer) => {
+        const ctl = checkControl(peer);
+        const keys = Array.isArray(args.keys) ? args.keys.map(String) : [];
+        if (keys.length === 0) throw new Error("keys: at least one key is required");
+        await ctl.keysSmart(String(args.target), keys);
+        return { ok: true, sent: keys };
+      })
+    },
+    // ---- pane-level control tools (socket API) -----------------------
+    // Unlike the bridge_agent_* tools (which require herdr to RECOGNIZE the
+    // agent), these drive any pane through the herdr local socket: physical
+    // input and output for agents herdr does not know (e.g. MiniMax Code).
+    {
+      name: "bridge_pane_list",
+      description: "List every herdr pane (ids, titles, agent status, cwd) via the herdr socket \u2014 including panes running agents herdr does not recognize. Use a paneId as `target` of bridge_pane_send / bridge_pane_keys / bridge_pane_read. Control tools: they type into real terminals \u2014 use with care.",
+      inputSchema: schema({}),
+      handler: wrap(true, async (_args, peer) => ({ panes: await checkControl(peer).paneList() }))
+    },
+    {
+      name: "bridge_pane_send",
+      description: "Type text into a herdr pane's input line (physical keystrokes via the herdr socket; works for ANY pane, no agent detection needed). This is how you drive an agent herdr does not recognize: the text lands in the target's terminal as if typed. Slash commands are executed by the target's TUI. With enter: true (default), the text is submitted with Enter.",
+      inputSchema: schema(
+        {
+          target: str("herdr paneId, e.g. wT:p2, from bridge_pane_list."),
+          text: str("Text to type into the pane (slash commands are executed, not sent as chat)."),
+          enter: { type: "boolean", description: "Submit with Enter after typing (default true)." }
+        },
+        ["target", "text"]
+      ),
+      handler: wrap(true, async (args, peer) => {
+        const ctl = checkControl(peer);
+        const paneId = String(args.target);
+        const text = String(args.text);
+        await ctl.paneSendText(paneId, text);
+        if (args.enter !== false) await ctl.paneSendKeys(paneId, ["Enter"]);
+        return { ok: true, target: paneId, sent: text };
+      })
+    },
+    {
+      name: "bridge_pane_keys",
+      description: "Send raw key presses to any herdr pane (Enter, esc, ctrl-c, arrows...). Use to dismiss permission prompts or interrupt a stuck program in a pane herdr does not recognize as an agent.",
+      inputSchema: schema(
+        {
+          target: str("herdr paneId, e.g. wT:p2, from bridge_pane_list."),
+          keys: { type: "array", items: { type: "string" }, description: 'Keys to send, e.g. ["Enter"], ["esc"], ["ctrl-c"].' }
+        },
+        ["target", "keys"]
+      ),
+      handler: wrap(true, async (args, peer) => {
+        const ctl = checkControl(peer);
+        const keys = Array.isArray(args.keys) ? args.keys.map(String) : [];
+        if (keys.length === 0) throw new Error("keys: at least one key is required");
+        await ctl.paneSendKeys(String(args.target), keys);
+        return { ok: true, sent: keys };
+      })
+    },
+    {
+      name: "bridge_pane_read",
+      description: "Read a herdr pane's recent terminal output (plain text, ANSI stripped). Use to collect the reply of an agent that is not connected to the hub or not recognized by herdr.",
+      inputSchema: schema(
+        {
+          target: str("herdr paneId, e.g. wT:p2, from bridge_pane_list."),
+          lines: int("How many lines to read (default: all recent)."),
+          source: { type: "string", enum: ["visible", "recent", "recent-unwrapped", "detection"], description: "Terminal snapshot source (default recent)." }
+        },
+        ["target"]
+      ),
+      handler: wrap(
+        true,
+        async (args, peer) => checkControl(peer).paneRead(String(args.target), {
+          lines: args.lines === void 0 ? void 0 : Number(args.lines),
+          source: args.source === void 0 ? void 0 : args.source
+        })
+      )
+    },
+    {
+      name: "bridge_pane_wait",
+      description: "Wait until a herdr pane's output matches a pattern (substring or regex) or the budget elapses \u2014 the pane-level counterpart of bridge_agent_wait for agents herdr does not recognize. Returns the matched pane output, or `matched: null` on timeout.",
+      inputSchema: schema(
+        {
+          target: str("herdr paneId, e.g. wT:p2, from bridge_pane_list."),
+          match: {
+            type: "object",
+            properties: {
+              type: { type: "string", enum: ["substring", "regex"], description: "Match kind (default substring)." },
+              value: { type: "string", description: "Text or regex to match in the pane output." }
+            },
+            required: ["value"],
+            description: "Output pattern to wait for."
+          },
+          timeoutMs: int("Wait cap in ms (default 30000).")
+        },
+        ["target", "match"]
+      ),
+      handler: wrap(true, async (args, peer) => {
+        const ctl = checkControl(peer);
+        const match = args.match ?? {};
+        if (typeof match.value !== "string" || match.value === "") throw new Error("match.value: a non-empty string is required");
+        const type = match.type === "regex" ? "regex" : "substring";
+        const read = await ctl.paneWaitForOutput(String(args.target), { type, value: match.value }, {
+          timeoutMs: args.timeoutMs === void 0 ? void 0 : Number(args.timeoutMs)
+        });
+        return read === null ? { matched: null } : { matched: read };
+      })
     }
   ];
 }
@@ -527,10 +1151,10 @@ var McpStreamableHttpServer = class {
   }
   sseStreams = /* @__PURE__ */ new Map();
   /** Attach request handling for `path` (e.g. `/mcp`) to an http server. */
-  attach(server, path) {
+  attach(server, path2) {
     server.on("request", (req, res) => {
       const url = new URL(req.url ?? "/", "http://localhost");
-      if (url.pathname !== path) {
+      if (url.pathname !== path2) {
         res.writeHead(404, { "Content-Type": "application/json" }).end(JSON.stringify({ error: "not found" }));
         return;
       }
@@ -710,7 +1334,7 @@ function readBody(req) {
 
 // src/index.ts
 var SERVER_NAME = "agent-comm-hub";
-var SERVER_VERSION = "0.2.0";
+var SERVER_VERSION = "0.4.0";
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 18764;
 var DEFAULT_PATH = "/mcp";
@@ -739,8 +1363,20 @@ function startHub(config = {}, log2 = console) {
     isPeerLive: (peerId) => livePeersFor(registry).has(peerId)
   });
   const registry = new SessionRegistry();
+  const herdr = new HerdrCtl({
+    bin: resolved.herdrBin,
+    baseArgs: resolved.herdrBaseArgs,
+    defaultTimeoutMs: resolved.herdrTimeoutMs,
+    socketPath: resolved.herdrSocketPath,
+    sendRequest: resolved.herdrSendRequest
+  });
   const mcp = new McpStreamableHttpServer(
-    hubTools(hub, registry, { defaultWaitMs: resolved.defaultWaitMs, waitTimeoutMs: resolved.waitTimeoutMs }),
+    hubTools(hub, registry, {
+      defaultWaitMs: resolved.defaultWaitMs,
+      waitTimeoutMs: resolved.waitTimeoutMs,
+      herdr,
+      herdrControlPeers: resolved.herdrControlPeers === "all" || resolved.herdrControlPeers === void 0 ? "all" : new Set(resolved.herdrControlPeers)
+    }),
     { name: SERVER_NAME, version: SERVER_VERSION },
     registry,
     (message) => log2.warn(message),
@@ -775,14 +1411,189 @@ function startHub(config = {}, log2 = console) {
 
 // src/setup.ts
 import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { existsSync as existsSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname2, join as join2 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/discover.ts
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, accessSync, readFileSync, constants as fsConstants } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+function registryFile() {
+  return join(dirname(fileURLToPath(import.meta.url)), "..", "agents", "registry.json");
+}
+function expandHome(file, home) {
+  return file.startsWith("~/") ? join(home, file.slice(2)) : file;
+}
+function expandConfigFile(file, home) {
+  const expanded = expandHome(file, home);
+  const star = expanded.indexOf("*");
+  if (star < 0) return [expanded];
+  const prefix = expanded.slice(0, star);
+  const suffix = expanded.slice(star + 1);
+  const base = prefix.slice(0, prefix.lastIndexOf(sep));
+  if (!existsSync(base)) return [];
+  return readdirSync(base, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => join(base, entry.name, suffix));
+}
+function validateRegistry(registry) {
+  if (!Array.isArray(registry.agents)) throw new Error('registry: missing "agents" array');
+  const ids = /* @__PURE__ */ new Set();
+  for (const agent of registry.agents) {
+    if (typeof agent.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(agent.id)) {
+      throw new Error(`registry: bad agent id ${JSON.stringify(agent.id)}`);
+    }
+    if (ids.has(agent.id)) throw new Error(`registry: duplicate agent id '${agent.id}'`);
+    ids.add(agent.id);
+    if (!Array.isArray(agent.probe)) throw new Error(`registry: ${agent.id}: probe must be an array`);
+    if (agent.npm !== void 0 && !Array.isArray(agent.npm)) throw new Error(`registry: ${agent.id}: npm must be an array`);
+    if (!Array.isArray(agent.configs)) throw new Error(`registry: ${agent.id}: configs must be an array`);
+    for (const config of agent.configs) {
+      if (typeof config.file !== "string" || !config.file.startsWith("~/")) {
+        throw new Error(`registry: ${agent.id}: config file must be '~'-relative`);
+      }
+      if (config.file.split("/").includes("..")) {
+        throw new Error(`registry: ${agent.id}: config file must not contain '..'`);
+      }
+      if (config.file.split("*").length > 2) {
+        throw new Error(`registry: ${agent.id}: at most one '*' segment allowed`);
+      }
+      if (!["json", "toml", "dsh"].includes(config.strategy)) {
+        throw new Error(`registry: ${agent.id}: unknown strategy '${config.strategy}'`);
+      }
+      if (config.strategy === "json" && (typeof config.section !== "string" || config.entry === null)) {
+        throw new Error(`registry: ${agent.id}: json strategy needs a section and an entry`);
+      }
+      if (config.strategy !== "json" && config.entry !== null) {
+        throw new Error(`registry: ${agent.id}: only json strategy may carry an entry`);
+      }
+    }
+    if (agent.skill !== null && (typeof agent.skill !== "string" || !agent.skill.startsWith("~/"))) {
+      throw new Error(`registry: ${agent.id}: skill must be '~'-relative or null`);
+    }
+    if (agent.os !== void 0 && (!Array.isArray(agent.os) || agent.os.some((os2) => !["win32", "darwin", "linux"].includes(os2)))) {
+      throw new Error(`registry: ${agent.id}: invalid os list`);
+    }
+  }
+}
+function loadRegistry(file = registryFile()) {
+  const registry = JSON.parse(readFileSync(file, "utf8"));
+  validateRegistry(registry);
+  return registry;
+}
+function commandOnPath(command, pathEnv, pathext, platform) {
+  const dirs = pathEnv.split(platform === "win32" ? ";" : ":");
+  const extensions = platform === "win32" ? ["", ...(pathext || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)] : [""];
+  for (const dir of dirs) {
+    const base = dir === "" ? "." : dir;
+    for (const ext of extensions) {
+      const candidate = join(base, command + ext);
+      try {
+        accessSync(candidate, fsConstants.X_OK);
+        return true;
+      } catch {
+      }
+    }
+  }
+  return false;
+}
+function readNpmNames(root) {
+  const names = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith("@")) {
+      const scopeDir = join(root, entry.name);
+      for (const sub of readdirSync(scopeDir, { withFileTypes: true })) {
+        if (sub.isDirectory()) names.push(sub.name);
+      }
+    } else {
+      names.push(entry.name);
+    }
+  }
+  return names;
+}
+function npmGlobalRoot(platform) {
+  try {
+    const out = execFileSync(platform === "win32" ? "npm.cmd" : "npm", ["root", "-g"], { encoding: "utf8", windowsHide: true }).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+function npmFallbackRoots(home, platform) {
+  if (platform === "win32") {
+    const appData = process.env.APPDATA ?? join(home, "AppData", "Roaming");
+    return [join(appData, "npm", "node_modules")];
+  }
+  return [
+    "/usr/local/lib/node_modules",
+    "/usr/lib/node_modules",
+    ...existsSync(join(home, ".nvm", "versions", "node")) ? readdirSync(join(home, ".nvm", "versions", "node")).map((dir) => join(home, ".nvm", "versions", "node", dir, "lib", "node_modules")) : []
+  ];
+}
+function discover(registry, options = {}) {
+  const home = options.homeDir ?? homedir();
+  const platform = options.platform ?? process.platform;
+  const pathEnv = options.pathEnv ?? process.env.PATH ?? "";
+  const pathext = options.pathext ?? process.env.PATHEXT ?? "";
+  let npmNames = null;
+  if (!options.noNpm) {
+    if (options.npmRoot !== void 0 && options.npmRoot !== null) {
+      npmNames = existsSync(options.npmRoot) ? readNpmNames(options.npmRoot) : [];
+    } else if (options.npmRoot !== null) {
+      const root = npmGlobalRoot(platform);
+      if (root && existsSync(root)) {
+        npmNames = readNpmNames(root);
+      } else {
+        npmNames = [];
+        for (const fallback of npmFallbackRoots(home, platform)) {
+          if (existsSync(fallback)) {
+            npmNames = readNpmNames(fallback);
+            break;
+          }
+        }
+      }
+    }
+  }
+  return registry.agents.filter((agent) => agent.os === void 0 || agent.os.includes(platform)).map((agent) => {
+    let source = "none";
+    const configFiles = [];
+    for (const config of agent.configs) {
+      for (const file of expandConfigFile(config.file, home)) {
+        if (existsSync(file)) {
+          configFiles.push(file);
+          if (source === "none") source = "config";
+        }
+      }
+    }
+    if (source === "none" && agent.probe.some((command) => commandOnPath(command, pathEnv, pathext, platform))) {
+      source = "path";
+    }
+    if (source === "none" && npmNames !== null && (agent.probe.some((command) => npmNames.includes(command)) || (agent.npm ?? []).some((name) => npmNames.includes(name)))) {
+      source = "npm";
+    }
+    return { id: agent.id, source, configFiles, present: source !== "none" };
+  });
+}
+function runDiscover(options = {}) {
+  const log2 = options.log ?? ((message) => console.log(message));
+  const found = discover(loadRegistry(), options);
+  log2("discovered agents:");
+  for (const agent of found) {
+    const status = agent.present ? agent.source : "not installed";
+    const files = agent.configFiles.length > 0 ? ` \u2014 ${agent.configFiles.join(", ")}` : "";
+    log2(`  ${agent.id.padEnd(16)} ${status}${files}`);
+  }
+  return found;
+}
+
+// src/setup.ts
 var DEFAULT_URL = "http://127.0.0.1:18764/mcp";
 var DEFAULT_SERVER = "agent-hub";
 function defaultSkillSrc() {
-  return join(dirname(fileURLToPath(import.meta.url)), "..", "agents", "SKILL.md");
+  return join2(dirname2(fileURLToPath2(import.meta.url)), "..", "agents", "SKILL.md");
 }
 function stamp() {
   const now = /* @__PURE__ */ new Date();
@@ -790,7 +1601,7 @@ function stamp() {
   return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
 }
 async function readJson(file) {
-  if (!existsSync(file)) return null;
+  if (!existsSync2(file)) return null;
   try {
     return JSON.parse(await readFile(file, "utf8"));
   } catch (error) {
@@ -798,7 +1609,7 @@ async function readJson(file) {
   }
 }
 async function writeJsonNoBom(file, doc) {
-  await mkdir(dirname(file), { recursive: true });
+  await mkdir(dirname2(file), { recursive: true });
   await writeFile(file, JSON.stringify(doc, null, 2) + "\n", "utf8");
 }
 async function backup(file) {
@@ -819,7 +1630,7 @@ function resolveSection(doc, section) {
   return node;
 }
 async function mergeJsonServer(file, section, entry, opts) {
-  if (!existsSync(file)) return "skipped";
+  if (!existsSync2(file)) return "skipped";
   const doc = await readJson(file);
   if (doc === null) return "skipped";
   const servers = resolveSection(doc, section);
@@ -841,7 +1652,7 @@ async function mergeJsonServer(file, section, entry, opts) {
   return "changed";
 }
 async function mergeTomlSection(file, opts) {
-  if (!existsSync(file)) return "skipped";
+  if (!existsSync2(file)) return "skipped";
   const text = await readFile(file, "utf8");
   const marker = `[mcp_servers.${opts.serverName}]`;
   const markerRe = new RegExp(`^\\[mcp_servers\\.${escapeRegExp(opts.serverName)}\\]`, "m");
@@ -865,31 +1676,104 @@ url = "${opts.url}"
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+var DSH_PATCH_MARKER = "# \u2500\u2500 agent-comm-hub MCP client";
+function dshPatchBlock(url, serverName) {
+  return `
+${DSH_PATCH_MARKER} (installed by \`agent-comm-hub setup\`; undo with \`setup --remove\`) \u2500
+- insert:
+    - id: ${serverName}
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: ${serverName}
+        transport: streamable-http
+        url: ${url}
+`;
+}
+async function mergeDshPatch(file, opts) {
+  if (!existsSync2(file)) return "skipped";
+  const text = await readFile(file, "utf8");
+  const lines = text.split("\n");
+  const markerLine = lines.findIndex((line) => line.includes(DSH_PATCH_MARKER));
+  const hasBlock = markerLine >= 0;
+  const blockRange = () => {
+    let entryStart = -1;
+    for (let i = markerLine + 1; i < lines.length; i++) {
+      if (/^- /.test(lines[i])) {
+        entryStart = i;
+        break;
+      }
+    }
+    let end = lines.length;
+    if (entryStart >= 0) {
+      for (let i = entryStart + 1; i < lines.length; i++) {
+        if (/^- /.test(lines[i])) {
+          end = i;
+          break;
+        }
+      }
+    }
+    let start = markerLine;
+    while (start > 0 && lines[start - 1].trim() === "") start--;
+    return { start, end };
+  };
+  const withoutBlock = () => {
+    const { start, end } = blockRange();
+    return lines.slice(0, start).concat(lines.slice(end)).join("\n");
+  };
+  if (opts.remove) {
+    if (!hasBlock) return "absent";
+    const cleaned = withoutBlock();
+    await backup(file);
+    await writeFile(file, cleaned, "utf8");
+    return "removed";
+  }
+  if (hasBlock) {
+    if (lines.some((line) => line.includes(`url: ${opts.url}`))) return "unchanged";
+    const replaced = withoutBlock();
+    await backup(file);
+    await writeFile(file, replaced.trimEnd() + dshPatchBlock(opts.url, opts.serverName), "utf8");
+    return "changed";
+  }
+  await backup(file);
+  await writeFile(file, text.trimEnd() + dshPatchBlock(opts.url, opts.serverName), "utf8");
+  return "changed";
+}
 async function syncSkill(skillDir, skillSrc, remove, log2) {
   if (remove) {
-    if (existsSync(skillDir)) {
-      await mkdir(dirname(skillDir), { recursive: true });
+    if (existsSync2(skillDir)) {
+      await mkdir(dirname2(skillDir), { recursive: true });
       await rmRecursive(skillDir);
       log2(`  skill removed: ${skillDir}`);
     }
     return;
   }
-  if (!existsSync(skillSrc)) {
+  if (!existsSync2(skillSrc)) {
     log2(`  SKILL.md source missing: ${skillSrc} (skipped)`);
     return;
   }
   await mkdir(skillDir, { recursive: true });
-  await copyFile(skillSrc, join(skillDir, "SKILL.md"));
-  log2(`  skill -> ${join(skillDir, "SKILL.md")}`);
+  await copyFile(skillSrc, join2(skillDir, "SKILL.md"));
+  log2(`  skill -> ${join2(skillDir, "SKILL.md")}`);
 }
 async function rmRecursive(dir) {
   const { rm } = await import("node:fs/promises");
   await rm(dir, { recursive: true, force: true });
 }
+function substitute(entry, values) {
+  const out = {};
+  for (const [key, value] of Object.entries(entry)) {
+    if (typeof value === "string") {
+      out[key] = value.replaceAll("{url}", values.url).replaceAll("{serverName}", values.serverName);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
 async function runSetup(options = {}) {
   const url = options.url ?? DEFAULT_URL;
   const serverName = options.serverName ?? DEFAULT_SERVER;
-  const home = options.homeDir ?? homedir();
+  const home = options.homeDir ?? homedir2();
   const skillSrc = options.skillSrc ?? defaultSkillSrc();
   const remove = options.remove === true;
   const log2 = options.log ?? ((message) => console.log(message));
@@ -899,43 +1783,40 @@ async function runSetup(options = {}) {
     else if (status === "unchanged" || status === "absent") summary.unchanged.push(`${label}: ${file}`);
     else if (status === "skipped") summary.skipped.push(`${label}: ${file}`);
   };
-  const jsonTargets = [
-    { label: "mcode", file: join(home, ".minimax", "mcp.json"), section: "mcpServers", entry: { url, type: "streamable-http", enabled: true, configured: true, timeout: 12e4, description: "agent-comm-hub: talk to every other agent connected to the hub." } },
-    { label: "mcode", file: join(home, ".minimax", "mcp", "mcp.json"), section: "mcpServers", entry: { url, type: "streamable-http", enabled: true, configured: true, timeout: 12e4, description: "agent-comm-hub: talk to every other agent connected to the hub." } },
-    { label: "opencode", file: join(home, ".config", "opencode", "opencode.json"), section: "mcp", entry: { type: "remote", url, enabled: true } },
-    { label: "kimi-code", file: join(home, ".kimi-code", "mcp.json"), section: "mcpServers", entry: { transport: "http", url, startupTimeoutMs: 3e4, toolTimeoutMs: 12e4 } },
-    { label: "gemini-cli", file: join(home, ".gemini", "settings.json"), section: "mcpServers", entry: { type: "http", url } },
-    { label: "zcode", file: join(home, ".zcode", "cli", "config.json"), section: "mcp.servers", entry: { type: "remote", url, enabled: true } }
-  ];
-  for (const target of jsonTargets) {
-    try {
-      const status = await mergeJsonServer(target.file, target.section, target.entry, { serverName, url, remove });
-      record(status, target.label, target.file);
-    } catch (error) {
-      summary.errors.push(`${target.label}: ${target.file} \u2014 ${error.message}`);
-      log2(`  ${target.label}: SKIPPED \u2014 ${error.message}`);
+  const registry = loadRegistry();
+  const found = discover(registry, { homeDir: home, pathEnv: options.pathEnv, noNpm: options.noNpm === true });
+  const only = options.agent;
+  let targetAgents = [];
+  if (only !== void 0) {
+    const match = registry.agents.find((agent) => agent.id === only);
+    if (match === void 0) {
+      log2(`agent '${only}' is not in the registry (see agents/registry.json)`);
+    } else {
+      targetAgents = [match];
+      log2(`configure only: ${only}`);
+    }
+  } else {
+    targetAgents = found.filter((agent) => agent.present).map((agent) => registry.agents.find((entry) => entry.id === agent.id));
+    const present2 = targetAgents.map((agent) => agent.id);
+    log2(`discovered: ${present2.length > 0 ? present2.join(", ") : "none"}`);
+  }
+  for (const agent of targetAgents) {
+    for (const config of agent.configs) {
+      for (const file of expandConfigFile(config.file, home)) {
+        try {
+          const status = config.strategy === "json" ? await mergeJsonServer(file, config.section, substitute(config.entry, { url, serverName }), { serverName, url, remove }) : config.strategy === "toml" ? await mergeTomlSection(file, { serverName, url, remove }) : await mergeDshPatch(file, { serverName, url, remove });
+          record(status, agent.id, file);
+        } catch (error) {
+          summary.errors.push(`${agent.id}: ${file} \u2014 ${error.message}`);
+          log2(`  ${agent.id}: SKIPPED \u2014 ${error.message}`);
+        }
+      }
     }
   }
-  const codexFile = join(home, ".codex", "config.toml");
-  try {
-    const status = await mergeTomlSection(codexFile, { serverName, url, remove });
-    record(status, "codex", codexFile);
-  } catch (error) {
-    summary.errors.push(`codex: ${codexFile} \u2014 ${error.message}`);
-    log2(`  codex: SKIPPED \u2014 ${error.message}`);
-  }
-  const skillDirs = [
-    join(home, ".agents", "skills", serverName),
-    // cross-agent standard
-    join(home, ".minimax", "skills", serverName),
-    join(home, ".config", "opencode", "skills", serverName),
-    join(home, ".kimi-code", "skills", serverName),
-    join(home, ".gemini", "skills", serverName),
-    join(home, ".codex", "skills", serverName),
-    join(home, ".zcode", "skills", serverName),
-    join(home, ".claude", "skills", serverName)
-    // config is manual; skill still useful
-  ];
+  const skillDirs = [join2(home, ".agents", "skills", serverName)];
+  for (const agent of targetAgents) {
+    if (agent.skill !== null) skillDirs.push(join2(expandHome(agent.skill, home), serverName));
+  }
   for (const dir of skillDirs) {
     try {
       await syncSkill(dir, skillSrc, remove, log2);
@@ -944,23 +1825,23 @@ async function runSetup(options = {}) {
       log2(`  skill ${dir}: SKIPPED \u2014 ${error.message}`);
     }
   }
-  if (remove) log2("done. Manual targets (see agents/README.md): Claude Code (.mcp.json), DSH (cordis.patch.yml).");
-  else log2("done. Manual targets (see agents/README.md): Claude Code (.mcp.json), DSH (cordis.patch.yml). Restart agent sessions to pick up the MCP server.");
+  if (remove) log2("done. Manual target (see agents/README.md): Claude Code (.mcp.json).");
+  else log2("done. Manual target (see agents/README.md): Claude Code (.mcp.json). Restart agent sessions (and the dsh profile) to pick up the MCP server.");
   return summary;
 }
 
 // src/ops.ts
-import { execFileSync } from "node:child_process";
+import { execFileSync as execFileSync2 } from "node:child_process";
 import { request } from "node:http";
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { dirname as dirname2, join as join2 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { mkdirSync, readFileSync as readFileSync2, rmSync, writeFileSync } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { dirname as dirname3, join as join3 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 async function runStatus(options = {}) {
   const host = options.host ?? "127.0.0.1";
   const port = options.port ?? 18764;
-  const path = options.path ?? "/mcp";
-  const url = options.url ?? `http://${host}:${port}${path}`;
+  const path2 = options.path ?? "/mcp";
+  const url = options.url ?? `http://${host}:${port}${path2}`;
   const probeName = "agent-comm-hub-cli";
   const notRunning = { running: false, url, peers: [] };
   try {
@@ -1007,8 +1888,8 @@ async function runStatus(options = {}) {
 function runUpdate() {
   const messages = [];
   try {
-    const pkgFile = join2(dirname2(fileURLToPath2(import.meta.url)), "..", "package.json");
-    const before = JSON.parse(readFileSync(pkgFile, "utf8")).version ?? "?";
+    const pkgFile = join3(dirname3(fileURLToPath3(import.meta.url)), "..", "package.json");
+    const before = JSON.parse(readFileSync2(pkgFile, "utf8")).version ?? "?";
     messages.push(`current version: ${before}`);
     const script = [
       "import { execFileSync } from 'node:child_process'",
@@ -1024,7 +1905,7 @@ function runUpdate() {
       "if (after === before) console.log('already up to date (v' + after + ')')",
       "else console.log('updated: v' + before + ' -> v' + after)"
     ].join("\n");
-    const out = execFileSync(process.execPath, ["--input-type=module", "-e", script], { encoding: "utf8", windowsHide: true });
+    const out = execFileSync2(process.execPath, ["--input-type=module", "-e", script], { encoding: "utf8", windowsHide: true });
     messages.push(out.trim());
     messages.push("restart the hub (agent-comm-hub) to pick up the new version");
     return { ok: true, messages };
@@ -1033,30 +1914,31 @@ function runUpdate() {
   }
 }
 function cliPath() {
-  return fileURLToPath2(import.meta.url);
+  return fileURLToPath3(import.meta.url);
 }
 function nodeExe() {
   return process.execPath;
 }
 function run(command, args, dryRun) {
   if (dryRun) return `[dry-run] ${command} ${args.join(" ")}`;
-  return execFileSync(command, args, { encoding: "utf8", windowsHide: true }).trim();
+  return execFileSync2(command, args, { encoding: "utf8", windowsHide: true }).trim();
 }
 function runService(options) {
   const messages = [];
   const port = options.port ?? 18764;
   const host = options.host ?? "127.0.0.1";
-  const path = options.path ?? "/mcp";
+  const path2 = options.path ?? "/mcp";
   const dryRun = options.dryRun === true;
+  const platform = options.platform ?? process.platform;
   try {
-    if (process.platform === "win32") {
-      const appData = process.env.APPDATA ?? join2(homedir2(), "AppData", "Roaming");
-      const launcherDir = join2(appData, "agent-comm-hub");
-      const vbs = join2(launcherDir, "agent-comm-hub.vbs");
+    if (platform === "win32") {
+      const appData = process.env.APPDATA ?? join3(homedir3(), "AppData", "Roaming");
+      const launcherDir = join3(appData, "agent-comm-hub");
+      const vbs = join3(launcherDir, "agent-comm-hub.vbs");
       const runKey = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
       const valueName = "agent-comm-hub";
       if (options.action === "install") {
-        const cmd = `"${nodeExe()}" "${cliPath()}" --host ${host} --port ${port} --path ${path}`;
+        const cmd = `"${nodeExe()}" "${cliPath()}" --host ${host} --port ${port} --path ${path2}`;
         const vbsContent = `CreateObject("WScript.Shell").Run "${cmd.replace(/"/g, '""')}", 0, False
 `;
         if (dryRun) {
@@ -1065,7 +1947,7 @@ function runService(options) {
         } else {
           mkdirSync(launcherDir, { recursive: true });
           writeFileSync(vbs, vbsContent);
-          execFileSync("reg", ["add", runKey, "/v", valueName, "/t", "REG_SZ", "/d", `wscript.exe "${vbs}"`, "/f"], { encoding: "utf8", windowsHide: true });
+          execFileSync2("reg", ["add", runKey, "/v", valueName, "/t", "REG_SZ", "/d", `wscript.exe "${vbs}"`, "/f"], { encoding: "utf8", windowsHide: true });
           messages.push(`auto-start registered: HKCU Run '${valueName}' -> hidden wscript launcher "${vbs}"`);
           messages.push(`start it now with: wscript.exe "${vbs}"`);
         }
@@ -1075,7 +1957,7 @@ function runService(options) {
           messages.push(`[dry-run] del ${vbs}`);
         } else {
           try {
-            execFileSync("reg", ["delete", runKey, "/v", valueName, "/f"], { encoding: "utf8", windowsHide: true });
+            execFileSync2("reg", ["delete", runKey, "/v", valueName, "/f"], { encoding: "utf8", windowsHide: true });
           } catch {
           }
           rmSync(launcherDir, { recursive: true, force: true });
@@ -1084,16 +1966,16 @@ function runService(options) {
       }
       return { ok: true, messages };
     }
-    if (process.platform === "linux") {
-      const unitDir = join2(homedir2(), ".config", "systemd", "user");
-      const unitFile = join2(unitDir, "agent-comm-hub.service");
+    if (platform === "linux") {
+      const unitDir = join3(homedir3(), ".config", "systemd", "user");
+      const unitFile = join3(unitDir, "agent-comm-hub.service");
       if (options.action === "install") {
         const unit = `[Unit]
 Description=agent-comm-hub (multi-peer MCP hub)
 After=network.target
 
 [Service]
-ExecStart=${nodeExe()} ${cliPath()} --host ${host} --port ${port} --path ${path}
+ExecStart=${nodeExe()} ${cliPath()} --host ${host} --port ${port} --path ${path2}
 Restart=on-failure
 
 [Install]
@@ -1121,7 +2003,72 @@ WantedBy=default.target
       }
       return { ok: true, messages };
     }
-    return { ok: false, messages: [`auto-start is not implemented for ${process.platform} \u2014 use pm2 or your platform's supervisor`] };
+    if (platform === "darwin") {
+      const launchAgentsDir = join3(homedir3(), "Library", "LaunchAgents");
+      const label = "com.agent-comm-hub";
+      const plist = join3(launchAgentsDir, `${label}.plist`);
+      const logFile = join3(homedir3(), "Library", "Logs", "agent-comm-hub.log");
+      const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+      const plistContent = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${label}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${nodeExe()}</string>
+    <string>${cliPath()}</string>
+    <string>--host</string><string>${host}</string>
+    <string>--port</string><string>${port}</string>
+    <string>--path</string><string>${path2}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${logFile}</string>
+  <key>StandardErrorPath</key>
+  <string>${logFile}</string>
+</dict>
+</plist>
+`;
+      if (options.action === "install") {
+        if (dryRun) {
+          messages.push(`[dry-run] write ${plist}`);
+          messages.push(`[dry-run] launchctl bootstrap gui/${uid} ${plist}`);
+        } else {
+          mkdirSync(launchAgentsDir, { recursive: true });
+          writeFileSync(plist, plistContent);
+          try {
+            execFileSync2("launchctl", ["bootstrap", `gui/${uid}`, plist], { encoding: "utf8", windowsHide: true });
+          } catch {
+            execFileSync2("launchctl", ["load", "-w", plist], { encoding: "utf8", windowsHide: true });
+          }
+          messages.push(`auto-start registered: launchd LaunchAgent ${plist}`);
+          messages.push(`start it now with: launchctl bootstrap gui/${uid} ${plist}`);
+        }
+      } else {
+        if (dryRun) {
+          messages.push(`[dry-run] launchctl bootout gui/${uid}/${label}`);
+          messages.push(`[dry-run] rm ${plist}`);
+        } else {
+          try {
+            execFileSync2("launchctl", ["bootout", `gui/${uid}/${label}`], { encoding: "utf8", windowsHide: true });
+          } catch {
+            try {
+              execFileSync2("launchctl", ["unload", "-w", plist], { encoding: "utf8", windowsHide: true });
+            } catch {
+            }
+          }
+          rmSync(plist, { force: true });
+          messages.push("auto-start removed (launchd LaunchAgent)");
+        }
+      }
+      return { ok: true, messages };
+    }
+    return { ok: false, messages: [`auto-start is not implemented for ${platform} \u2014 use pm2 or your platform's supervisor`] };
   } catch (error) {
     return { ok: false, messages: [`${error.message}`] };
   }
@@ -1130,8 +2077,8 @@ WantedBy=default.target
 // src/cli.ts
 function parseArgs(argv) {
   const args = {};
-  const numeric = /* @__PURE__ */ new Set(["--port", "--max-queue", "--history-limit", "--wait-timeout-ms", "--default-wait-ms", "--connected-window-ms", "--peer-idle-timeout-ms"]);
-  const string = /* @__PURE__ */ new Set(["--host", "--path", "--url", "--server-name"]);
+  const numeric = /* @__PURE__ */ new Set(["--port", "--max-queue", "--history-limit", "--wait-timeout-ms", "--default-wait-ms", "--connected-window-ms", "--peer-idle-timeout-ms", "--herdr-timeout-ms"]);
+  const string = /* @__PURE__ */ new Set(["--host", "--path", "--url", "--server-name", "--agent", "--herdr-bin"]);
   for (let i = 0; i < argv.length; i++) {
     const flag = argv[i];
     if (flag === "--help" || flag === "-h" || flag === "--version" || flag === "-V") {
@@ -1167,10 +2114,13 @@ Usage:
                                            every installed agent (incremental,
                                            idempotent; --remove undoes)
   agent-comm-hub status [options]          show hub health + online peers
+  agent-comm-hub discover                  list installed agents (registry-
+                                           driven; no config changes)
   agent-comm-hub service install|uninstall [options]
                                            one-shot auto-start (Windows Run
                                            key + hidden VBS launcher, no admin;
-                                           Linux systemd; --dry-run prints)
+                                           Linux systemd, macOS launchd;
+                                           --dry-run prints)
   agent-comm-hub update                  self-update from the npm registry
                                            (files updated in place; restart
                                            the hub afterwards)
@@ -1185,10 +2135,14 @@ Hub options:
   --default-wait-ms <n>    bridge_wait default budget (default 30000)
   --connected-window-ms <n>  Peer counts as active within this window (default 30000)
   --peer-idle-timeout-ms <n> Auto-unregister idle peers after this; 0 disables (default 600000)
+  --herdr-bin <path>         herdr CLI binary for bridge_agent_* control tools
+                             (default herdr, resolved via PATH)
+  --herdr-timeout-ms <n>     Default cap for one herdr call in ms (default 30000)
 
 Setup options:
   --url <url>              Hub endpoint to register (default http://127.0.0.1:18764/mcp)
   --server-name <name>     Config key (default agent-hub)
+  --agent <id>             Only configure one registry agent (e.g. codex)
   --remove                 Uninstall instead of install
 
   -h, --help               Show this help
@@ -1213,11 +2167,16 @@ try {
     await runSetup({
       url: args2["--url"],
       serverName: args2["--server-name"],
+      agent: args2["--agent"],
       remove: args2["--remove"] === true,
       log: (message) => log.info(message)
     });
     process.exit(0);
   }
+  if (command === "discover") {
+    runDiscover({ log: (message) => log.info(message) });
+    process.exit(0);
+  }
   if (command === "status") {
     const args2 = parseArgs(rest);
     const result = await runStatus({
@@ -1294,7 +2253,9 @@ try {
     waitTimeoutMs: args["--wait-timeout-ms"],
     defaultWaitMs: args["--default-wait-ms"],
     connectedWindowMs: args["--connected-window-ms"],
-    peerIdleTimeoutMs: args["--peer-idle-timeout-ms"]
+    peerIdleTimeoutMs: args["--peer-idle-timeout-ms"],
+    herdrBin: args["--herdr-bin"],
+    herdrTimeoutMs: args["--herdr-timeout-ms"]
   }, log);
   const shutdown = () => {
     log.info("agent-comm-hub shutting down");