agent-comm-hub 0.2.0 → 0.3.0

package/lib/index.js

@@ -1,6 +1,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";
 
@@ -294,6 +705,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);
@@ -419,6 +846,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 };
+      })
     }
   ];
 }
@@ -530,10 +1154,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;
       }
@@ -713,7 +1337,7 @@ function readBody(req) {
 
 // src/index.ts
 var SERVER_NAME = "agent-comm-hub";
-var SERVER_VERSION = "0.2.0";
+var SERVER_VERSION = "0.3.0";
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 18764;
 var DEFAULT_PATH = "/mcp";
@@ -742,8 +1366,20 @@ function startHub(config = {}, log = 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) => log.warn(message),
@@ -776,12 +1412,14 @@ function startHub(config = {}, log = console) {
   };
 }
 export {
+  AGENT_STATUSES,
   AgentHub,
   BROADCAST,
   DEFAULT_CONFIG,
   DEFAULT_HOST,
   DEFAULT_PATH,
   DEFAULT_PORT,
+  HerdrCtl,
   KINDS,
   McpStreamableHttpServer,
   PEER_ID_PATTERN,