agent-coord-mcp 0.26.22 → 0.26.23

package/src/transports/herdr.ts

@@ -0,0 +1,311 @@
+/**
+ * THE HERDR TRANSPORT — the second implementation of the seam (Phase 5.4 Task 4).
+ *
+ * herdr is a RUST BINARY (brew / herdr.dev / GitHub releases), NOT an npm package:
+ * `npm view herdr` answers 0.0.0 "Reserved package name" (spike 1.1). Nothing here is
+ * imported; every call is `herdr <subcommand>` over the socket API on this host, through
+ * one injectable runner so the transport can be exercised without a herdr server and
+ * measured against one when it is there.
+ *
+ * WHAT IS DIFFERENT FROM TMUX, and why each difference is a stated behaviour rather
+ * than a quiet default:
+ *   · NO PUSHER PROCESS. Delivery is a socket call made by the server itself; a marker
+ *     carries pid 0. Liveness is therefore never a pid heuristic — `probe` asks herdr
+ *     for the pane and its OWN `agent_status` (spike 1.4: live / wedged / killed are
+ *     three distinguishable answers there, which they are not on tmux).
+ *   · ERRORS ARE JSON, ON EITHER STREAM. `herdr pane get w999:p1` prints
+ *     {"error":{"code":"pane_not_found",…}} — measured on stdout with exit 0 in one call
+ *     and on stderr in another (a pane closed moments before read as "could not describe"
+ *     until the runner parsed stderr too). The runner parses whichever stream carries a
+ *     JSON body; the exit code alone would call failures successes.
+ *   · KEY NAMES ARE NOT PORTABLE. `ctrl+u` is accepted, `C-u` / `ctrl-u` are rejected
+ *     with {"error":{"code":"invalid_key"}} (spike, and measured again here). The seam
+ *     takes INTENTS; the one place a key name is spelled is `herdrKeyName`, which
+ *     REFUSES a tmux-vocabulary name rather than translating it by guess.
+ *   · THE ENTER RACE IS REAL. `send-text` then `send-keys enter` did not submit once in
+ *     the spike; the line sat in Claude's input box until a second enter. `push` and
+ *     `sendControl` VERIFY by reading the pane back and retry the enter once, and report
+ *     how many enters it took — measured per delivery, never assumed away.
+ *   · THE SLASH IS EATEN DOWNSTREAM OF ANY TRANSPORT (spike 1.3, ⟨q-f14692ca⟩ struck):
+ *     Claude Code interprets a leading `/` however the characters arrive. This transport
+ *     delivers bytes verbatim and makes no claim about what the reader does with them.
+ *   · ABSENT BINARY / STOPPED SERVER → an explicit refusal that NAMES herdr. Never a
+ *     silent fall-through to tmux: the config layer already refuses unknown kinds for the
+ *     same reason (identical evidence for a typo and a default).
+ */
+import { spawnSync } from "node:child_process";
+import type { ControlCommand, Liveness, Transport, TransportKind, TransportMarker } from "./types.js";
+import { HERDR, targetOf } from "./types.js";
+
+export type HerdrError = { code: string; message: string };
+export type HerdrResult = {
+  ok: boolean;
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  /** Parsed JSON body when herdr printed one. */
+  json?: unknown;
+  /** herdr's own error object, or a synthetic one for a missing binary. */
+  error?: HerdrError;
+  /** The binary itself is not on PATH. */
+  absent?: boolean;
+};
+export type HerdrRunner = (args: string[]) => HerdrResult;
+
+export const HERDR_BINARY = "herdr";
+export const HERDR_ABSENT_MESSAGE =
+  `herdr binary not found on PATH — herdr is a Rust binary (brew install herdr, or https://herdr.dev), ` +
+  `NOT an npm package (npm's "herdr" is a reserved 0.0.0 name). Install it, or use the tmux-push transport.`;
+
+/**
+ * Interpret a herdr reply — PURE, so the one rule it holds (a JSON error body on either
+ * stream is a refusal, whatever the exit code) is testable without a herdr on the host.
+ */
+export function interpretHerdrReply(r: { status: number | null; stdout?: string | null; stderr?: string | null }): HerdrResult {
+  const stdout = r.stdout ?? "";
+  const stderr = r.stderr ?? "";
+  let json: unknown;
+  for (const stream of [stdout, stderr]) {
+    const trimmed = stream.trim();
+    if (!trimmed.startsWith("{")) continue;
+    try { json = JSON.parse(trimmed); break; } catch { /* not a JSON body */ }
+  }
+  const err = (json as { error?: HerdrError } | undefined)?.error;
+  if (err && typeof err.code === "string") return { ok: false, status: r.status, stdout, stderr, json, error: err };
+  if (r.status !== 0) return { ok: false, status: r.status, stdout, stderr, json, error: { code: "exit", message: (stderr || stdout).trim() || `herdr exited ${r.status}` } };
+  return { ok: true, status: r.status, stdout, stderr, json };
+}
+
+/** Run `herdr <args>` and interpret the reply. */
+export function defaultHerdrRunner(args: string[]): HerdrResult {
+  const r = spawnSync(HERDR_BINARY, args, { encoding: "utf8" });
+  if (r.error && (r.error as NodeJS.ErrnoException).code === "ENOENT") {
+    return { ok: false, status: null, stdout: "", stderr: "", absent: true, error: { code: "binary_absent", message: HERDR_ABSENT_MESSAGE } };
+  }
+  return interpretHerdrReply({ status: r.status, stdout: r.stdout, stderr: r.stderr });
+}
+
+/**
+ * THE KEY VOCABULARY, in one place. Intents on the left, herdr's names on the right.
+ * A tmux-vocabulary name (`C-u`, `ctrl-u`, `M-x`) is REFUSED, never translated by guess:
+ * herdr would reject it as invalid_key, and a transport that "helpfully" rewrote it could
+ * just as easily rewrite it wrong and type garbage into a pane.
+ */
+export const HERDR_KEYS: Readonly<Record<string, string>> = Object.freeze({
+  enter: "enter",
+  escape: "esc",
+  "clear-line": "ctrl+u",
+});
+export function herdrKeyName(intentOrName: string): { ok: true; key: string } | { ok: false; error: string } {
+  const s = String(intentOrName ?? "").trim();
+  if (/^(?:C|M|S)-/i.test(s) || /^(?:ctrl|alt|meta|shift)-/i.test(s)) {
+    return { ok: false, error: `key '${s}' is tmux vocabulary and herdr rejects it as invalid_key — the herdr form is '${s.replace(/^(?:C|ctrl)-/i, "ctrl+").replace(/^(?:M|alt|meta)-/i, "alt+")}'; refused rather than guessed` };
+  }
+  if (HERDR_KEYS[s]) return { ok: true, key: HERDR_KEYS[s] };
+  if (/^[a-z0-9]+(?:\+[a-z0-9]+)*$/.test(s)) return { ok: true, key: s };
+  return { ok: false, error: `key '${s}' is not a herdr key name (letters, digits and '+', e.g. ctrl+u) and not a known intent (${Object.keys(HERDR_KEYS).join(", ")})` };
+}
+
+type PaneInfo = { pane_id?: string; agent_status?: string; agent?: string; workspace_id?: string };
+type ProcessInfo = { foreground_processes?: { argv?: string[]; pid?: number; name?: string }[]; shell_pid?: number };
+
+function paneOf(r: HerdrResult): PaneInfo | undefined {
+  const j = r.json as { result?: { pane?: PaneInfo; root_pane?: PaneInfo } } | undefined;
+  return j?.result?.pane ?? j?.result?.root_pane;
+}
+function processInfoOf(r: HerdrResult): ProcessInfo | undefined {
+  return (r.json as { result?: { process_info?: ProcessInfo } } | undefined)?.result?.process_info;
+}
+const LIVE_STATUSES = new Set(["idle", "working", "blocked", "done"]);
+
+export type HerdrTransportOptions = {
+  run?: HerdrRunner;
+  /** Milliseconds to wait before reading a pane back after typing. */
+  settleMs?: number;
+  /** Sleep, injectable so tests do not wait. */
+  sleep?: (ms: number) => void;
+  /** Lines of pane to read back when verifying a delivery. */
+  readLines?: number;
+};
+
+export class HerdrTransport implements Transport {
+  readonly kind: TransportKind = HERDR;
+  #run: HerdrRunner;
+  #settleMs: number;
+  #sleep: (ms: number) => void;
+  #readLines: number;
+
+  constructor(opts: HerdrTransportOptions = {}) {
+    this.#run = opts.run ?? defaultHerdrRunner;
+    // MEASURED on a shell pane in a task-owned workspace: after a single enter the output had
+    // rendered by 400 ms and not by 150 ms — below that, render lag reads as an unsubmitted
+    // line and the retry fires an empty enter (harmless, but counted). The genuine lost enter
+    // the spike measured is Claude's input box; the retry exists for that, bounded to one.
+    this.#settleMs = opts.settleMs ?? 400;
+    this.#sleep = opts.sleep ?? ((ms) => { const end = Date.now() + ms; while (Date.now() < end) { /* spin: tiny and rare */ } });
+    this.#readLines = opts.readLines ?? 12;
+  }
+
+  /** Is herdr on this host AND is its server running? Both, or the reason. */
+  availability(): { available: boolean; reason: string } {
+    const r = this.#run(["status"]);
+    if (r.absent) return { available: false, reason: HERDR_ABSENT_MESSAGE };
+    if (!r.ok) return { available: false, reason: `herdr status failed: ${r.error?.message ?? r.stderr}` };
+    const running = /server:[\s\S]*status:\s*running/.test(r.stdout);
+    return running
+      ? { available: true, reason: `herdr server running (${(r.stdout.match(/version:\s*(\S+)/) ?? [])[1] ?? "version unread"})` }
+      : { available: false, reason: `herdr binary present but its server is not running (herdr status: ${r.stdout.trim().split("\n").slice(-2).join(" ")}) — start herdr, or use the tmux-push transport` };
+  }
+  available(): boolean {
+    return this.availability().available;
+  }
+
+  /**
+   * Attach = verify the pane and return a marker. No process is spawned: the marker's pid
+   * is 0 and its `target` is the herdr pane id. Persisting the marker is the tool's job,
+   * exactly as for tmux.
+   */
+  async attach(args: { agentId: string; target?: string; includeRoom?: boolean; allowlist?: string[]; debounceMs?: number }): Promise<TransportMarker> {
+    const avail = this.availability();
+    if (!avail.available) throw new Error(`herdr transport cannot attach '${args.agentId}': ${avail.reason}`);
+    let target = args.target ?? process.env.HERDR_PANE_ID;
+    if (!target) {
+      const cur = this.#run(["pane", "current"]);
+      target = paneOf(cur)?.pane_id;
+    }
+    if (!target) {
+      throw new Error("herdr target not provided and this process is not inside a herdr pane (no HERDR_PANE_ID, `herdr pane current` answered nothing). Pass target explicitly (e.g. 'w2:p1').");
+    }
+    const got = this.#run(["pane", "get", target]);
+    if (!got.ok) throw new Error(`herdr pane '${target}' not found: ${got.error?.message ?? got.stderr}`);
+    return {
+      agentId: args.agentId,
+      transport: HERDR,
+      pid: 0,
+      target,
+      tmuxTarget: target,
+      since: Date.now(),
+      rooms: args.includeRoom !== false,
+    };
+  }
+
+  /** Does the pane exist, per herdr, through THIS transport's runner? null = could not ask. */
+  paneExists(target: string): boolean | null {
+    return herdrPaneExists(target, this.#run);
+  }
+
+  /** Nothing to kill: there is no pusher. The tool deletes the marker. */
+  async detach(_agentId: string): Promise<void> {
+    return;
+  }
+
+  /**
+   * Type `text` into the pane and press enter; VERIFY by reading the pane back, and if
+   * the line is still sitting unsubmitted (the spike's race), press enter once more.
+   * Reports the enters it took so the race is measured on every delivery.
+   */
+  async push(marker: TransportMarker, text: string): Promise<{ delivered: boolean; error?: string; enters?: number; verified?: boolean }> {
+    const avail = this.availability();
+    if (!avail.available) return { delivered: false, error: avail.reason };
+    const target = targetOf(marker);
+    if (!target) return { delivered: false, error: "no target recorded on the marker" };
+    const typed = this.#run(["pane", "send-text", target, text]);
+    if (!typed.ok) return { delivered: false, error: `send-text to ${target} refused: ${typed.error?.message ?? typed.stderr}` };
+    const enterKey = herdrKeyName("enter");
+    if (!enterKey.ok) return { delivered: false, error: enterKey.error };
+    let enters = 0;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const pressed = this.#run(["pane", "send-keys", target, enterKey.key]);
+      if (!pressed.ok) return { delivered: false, error: `send-keys enter to ${target} refused: ${pressed.error?.message ?? pressed.stderr}`, enters };
+      enters++;
+      this.#sleep(this.#settleMs);
+      const pending = this.#stillPending(target, text);
+      if (pending === false) return { delivered: true, enters, verified: true };
+      if (pending === null) return { delivered: true, enters, verified: false };
+    }
+    return { delivered: false, enters, verified: true, error: `text still sitting unsubmitted in ${target}'s input after ${enters} enters` };
+  }
+
+  /**
+   * Read the pane back: is the typed text still the LAST non-empty line (unsubmitted)?
+   * true = pending · false = submitted · null = could not read (unverified, not failed).
+   */
+  #stillPending(target: string, text: string): boolean | null {
+    const read = this.#run(["pane", "read", target, "--source", "visible", "--lines", String(this.#readLines), "--format", "text"]);
+    if (!read.ok) return null;
+    const lines = read.stdout.split("\n").map((l) => l.replace(/\s+$/, "")).filter((l) => l.trim().length > 0);
+    const last = lines.at(-1) ?? "";
+    const firstLine = text.split("\n")[0];
+    return last.endsWith(firstLine) && !/^[⏺✔✖]/.test(last);
+  }
+
+  /**
+   * THREE ANSWERS FROM HERDR'S OWN STATUS, never a pid heuristic:
+   *   · not a herdr marker / no target / herdr unavailable → unknown, naming which
+   *   · pane_not_found                                     → dead
+   *   · agent_status idle | working | blocked | done       → live (blocked IS live: it waits on a person)
+   *   · agent_status unknown, a foreground process present → unknown, naming the process (the wedged shape)
+   *   · agent_status unknown, nothing in the foreground    → unknown (a shell pane nobody is in)
+   */
+  async probe(marker: TransportMarker): Promise<Liveness> {
+    if (marker.transport !== HERDR) return { state: "unknown", reason: `transport "${marker.transport}" is not herdr` };
+    const target = targetOf(marker);
+    if (!target) return { state: "unknown", reason: "no target recorded on the marker" };
+    const avail = this.availability();
+    if (!avail.available) return { state: "unknown", reason: avail.reason };
+    const got = this.#run(["pane", "get", target]);
+    if (!got.ok) {
+      if (got.error?.code === "pane_not_found") return { state: "dead", reason: `herdr reports pane ${target} not found (${got.error.message})` };
+      return { state: "unknown", reason: `herdr could not describe pane ${target}: ${got.error?.message ?? got.stderr}` };
+    }
+    const status = String(paneOf(got)?.agent_status ?? "unknown");
+    if (LIVE_STATUSES.has(status)) return { state: "live" };
+    const proc = this.#run(["pane", "process-info", "--pane", target]);
+    const fg = processInfoOf(proc)?.foreground_processes ?? [];
+    if (fg.length) {
+      const p = fg[0];
+      return { state: "unknown", reason: `herdr reports agent_status "${status}" for pane ${target}; foreground process ${JSON.stringify(p.argv ?? [p.name])} (pid ${p.pid}) — present but not a recognised agent` };
+    }
+    return { state: "unknown", reason: `herdr reports agent_status "${status}" for pane ${target} and no foreground process` };
+  }
+
+  /**
+   * A control command is typed as `/<cmd>` and verified to have LEFT the input, with the
+   * same enter-race handling as push. All three commands ride the path the spike measured
+   * for /clear; compact and reload-skills are the same delivery path (spike: inferred,
+   * not measured) and are said so in the result.
+   */
+  async sendControl(marker: TransportMarker, cmd: ControlCommand): Promise<{ ok: boolean; error?: string; enters?: number; note?: string }> {
+    const r = await this.push(marker, `/${cmd}`);
+    if (!r.delivered) return { ok: false, error: r.error ?? "control not delivered", enters: r.enters };
+    return {
+      ok: true,
+      enters: r.enters,
+      note: cmd === "clear" ? "measured end to end in the spike" : `same delivery path as /clear; ${cmd} itself was inferred, not measured, by the spike`,
+    };
+  }
+
+  /**
+   * No pusher to kill. A herdr marker whose pane is gone is reaped (the caller deletes
+   * the marker); an unknown answer is unprobeable; a live pane is left alone.
+   */
+  async reapWedged(markers: TransportMarker[]): Promise<{ reaped: string[]; unprobeable: string[] }> {
+    const reaped: string[] = [];
+    const unprobeable: string[] = [];
+    for (const marker of markers) {
+      const live = await this.probe(marker);
+      if (live.state === "dead") reaped.push(marker.agentId);
+      else if (live.state === "unknown") unprobeable.push(marker.agentId);
+    }
+    return { reaped, unprobeable };
+  }
+}
+
+/** Synchronous pane-existence read for the registry's liveness path (no pid to check). */
+export function herdrPaneExists(target: string, run: HerdrRunner = defaultHerdrRunner): boolean | null {
+  const r = run(["pane", "get", target]);
+  if (r.absent) return null;
+  if (r.ok) return true;
+  if (r.error?.code === "pane_not_found") return false;
+  return null;
+}

package/src/transports/index.ts

@@ -6,13 +6,15 @@
  * fall-through at a call site. Until Task 3, tmux is the only registered
  * implementation and that is the rollback plan — the seam lands behind no config.
  */
-import { HERDR, TMUX_PUSH, TMUX_PUSH_REMOTE, type Transport, type TransportKind } from "./types.js";
+import { HERDR, TMUX_PUSH, TMUX_PUSH_REMOTE, TRANSPORT_KINDS, type Transport, type TransportKind } from "./types.js";
 import { TmuxTransport, type TmuxHost } from "./tmux.js";
+import { HerdrTransport } from "./herdr.js";
 import { configuredTransport } from "./config.js";
 
 export * from "./types.js";
 export * from "./config.js";
 export { TmuxTransport, tmuxAvailable, paneExists, probePane, tmuxVersion, type TmuxHost } from "./tmux.js";
+export { HerdrTransport, defaultHerdrRunner, interpretHerdrReply, herdrKeyName, herdrPaneExists, HERDR_KEYS, HERDR_ABSENT_MESSAGE, type HerdrRunner, type HerdrResult } from "./herdr.js";
 
 let host: TmuxHost | undefined;
 
@@ -33,9 +35,13 @@ export function resolveTransport(kind: TransportKind): Transport {
     case TMUX_PUSH_REMOTE:
       return new TmuxTransport(host, kind);
     case HERDR:
-      // Task 4. Named so the union stays total and the gap is a stated absence
-      // rather than a default that silently behaves like tmux.
-      throw new Error('transport "herdr" is not implemented yet (Phase 5.4 Task 4)');
+      // Task 4: the socket transport. No host object — there is no pusher process to
+      // inject; every call is `herdr <subcommand>` through the transport's own runner.
+      return new HerdrTransport();
+    default:
+      // Unreachable for a TransportKind; reachable from JS with a string. A designed
+      // refusal, never a default that behaves like tmux.
+      throw new Error(`unknown transport kind ${JSON.stringify(kind)} — valid: ${TRANSPORT_KINDS.join(", ")}`);
   }
 }