agent-coord-mcp 0.26.19 → 0.26.20

package/src/transports/tmux.ts

@@ -0,0 +1,177 @@
+/**
+ * THE TMUX TRANSPORT — every `tmux` shell-out in this package, in one file.
+ *
+ * Before this, `spawnSync("tmux", …)` appeared at 7 sites in `tools/transport.ts`
+ * and the `has-session` caveat below was written out TWICE, verbatim, at two of
+ * them. A rule duplicated in two comments is a rule that will be re-derived
+ * wrongly at the third site somebody adds.
+ *
+ * WHAT THIS FILE DOES NOT DO, on purpose: spawn or reap the pusher process,
+ * read receipts, or schedule reminders. Delivery is a second process for THIS
+ * transport and will not be for a socket one, so that machinery stays with the
+ * tools that own it and reaches this file through `TmuxHost` below. An interface
+ * that baked in a pusher could not host an implementation that has none.
+ */
+import { spawnSync } from "node:child_process";
+import type { ControlCommand, Liveness, Transport, TransportMarker, TransportKind } from "./types.js";
+import { TMUX_PUSH, isLocallyProbeable, isTmuxKind, targetOf } from "./types.js";
+
+/**
+ * The parts of delivery that belong to the PROCESS layer, not to tmux.
+ *
+ * Injected rather than imported to keep the dependency pointing one way:
+ * `tools/transport.ts` owns pusher spawn, receipts and marker files, and hands
+ * them here. Importing them back would make this module and that one mutually
+ * dependent, and a cycle is how "one place for the literal" quietly becomes two.
+ */
+export type TmuxHost = {
+  attach(args: {
+    agentId: string;
+    target?: string;
+    includeRoom?: boolean;
+    allowlist?: string[];
+    debounceMs?: number;
+  }): Promise<TransportMarker>;
+  detach(agentId: string): Promise<void>;
+  push(marker: TransportMarker, text: string): Promise<{ delivered: boolean; error?: string }>;
+  sendControl(marker: TransportMarker, cmd: ControlCommand): Promise<{ ok: boolean; error?: string }>;
+  /** Is the pusher process behind this marker still running on this host? */
+  pusherAlive(marker: TransportMarker): boolean;
+  /** Stop a wedged pusher. Returns false if it could not be signalled. */
+  killPusher(marker: TransportMarker): boolean;
+};
+
+/** `tmux -V` — is tmux on this host at all? */
+export function tmuxAvailable(): boolean {
+  return spawnSync("tmux", ["-V"]).status === 0;
+}
+
+/**
+ * DOES THIS TARGET EXIST? The only tmux probe with discriminating power.
+ *
+ * `has-session` VALIDATES THE TARGET; `display-message -p -t <target> "ok"`
+ * DOES NOT — tmux exits 0 for any target, including a pane killed a moment ago,
+ * so that probe had ZERO discriminating power and reported every dead pane
+ * alive. Pinned to the BEHAVIOUR, not a version: measured identical on tmux
+ * 3.6b, 3.7b. A version-pinned claim rots on the next upgrade.
+ *
+ * Positive control, both directions, re-run on tmux 3.7b while extracting this:
+ * bogus target `%99999` -> has-session exit 1, display-message exit 0; live pane
+ * `%8` -> both exit 0. The wrong probe is wrong in only one direction, which is
+ * why it survived: it never reports a live pane dead.
+ */
+export function paneExists(target: string): boolean {
+  return spawnSync("tmux", ["has-session", "-t", target]).status === 0;
+}
+
+/**
+ * `has-session` with the failure text, for the one caller that reports it.
+ *
+ * `paneExists` is the boolean most sites want; attach quotes tmux's own stderr
+ * back to the user, and losing that text would make a refusal less useful while
+ * still typechecking — the exact class of silent regression this task guards.
+ */
+export function probePane(target: string): { exists: boolean; stderr: string } {
+  const probe = spawnSync("tmux", ["has-session", "-t", target]);
+  return { exists: probe.status === 0, stderr: (probe.stderr ?? "").toString().trim() };
+}
+
+/** `tmux -V` output, or undefined when tmux is absent. */
+export function tmuxVersion(): string | undefined {
+  const probe = spawnSync("tmux", ["-V"]);
+  if (probe.status !== 0) return undefined;
+  return (probe.stdout ?? "").toString().trim() || undefined;
+}
+
+export class TmuxTransport implements Transport {
+  readonly kind: TransportKind;
+  #host: TmuxHost;
+
+  constructor(host: TmuxHost, kind: TransportKind = TMUX_PUSH) {
+    this.#host = host;
+    this.kind = kind;
+  }
+
+  available(): boolean {
+    return tmuxAvailable();
+  }
+
+  attach(args: {
+    agentId: string;
+    target?: string;
+    includeRoom?: boolean;
+    allowlist?: string[];
+    debounceMs?: number;
+  }): Promise<TransportMarker> {
+    return this.#host.attach(args);
+  }
+
+  detach(agentId: string): Promise<void> {
+    return this.#host.detach(agentId);
+  }
+
+  push(marker: TransportMarker, text: string): Promise<{ delivered: boolean; error?: string }> {
+    return this.#host.push(marker, text);
+  }
+
+  sendControl(marker: TransportMarker, cmd: ControlCommand): Promise<{ ok: boolean; error?: string }> {
+    return this.#host.sendControl(marker, cmd);
+  }
+
+  /**
+   * THREE ANSWERS, AND THE THIRD IS LOAD-BEARING.
+   *
+   * Each `unknown` below was previously a `continue` with a comment. The states
+   * are preserved exactly, because "we could not look" is not evidence of death
+   * and a reaper that cannot tell them apart kills live sessions:
+   *
+   * · not a tmux marker        -> unknown (this transport cannot speak for it)
+   * · remote (foreign host)    -> unknown (no local pane; heartbeat decides)
+   * · no target recorded       -> unknown (nothing to probe)
+   * · tmux missing on host     -> unknown (the instrument is absent, not the pane)
+   * · target absent            -> dead
+   * · pusher gone, pane alive  -> dead, and it says which half failed
+   */
+  async probe(marker: TransportMarker): Promise<Liveness> {
+    if (!isTmuxKind(marker.transport)) {
+      return { state: "unknown", reason: `transport "${marker.transport}" is not tmux` };
+    }
+    if (!isLocallyProbeable(marker.transport)) {
+      return {
+        state: "unknown",
+        reason: `${marker.transport} runs on another host${marker.host ? ` (${marker.host})` : ""} — no local pane to probe; liveness is heartbeat-based`,
+      };
+    }
+    const target = targetOf(marker);
+    if (!target) return { state: "unknown", reason: "no target recorded on the marker" };
+    if (!tmuxAvailable()) return { state: "unknown", reason: "tmux is not available on this host" };
+    if (!paneExists(target)) return { state: "dead", reason: `pane ${target} does not exist` };
+    if (!this.#host.pusherAlive(marker)) {
+      return { state: "dead", reason: `pane ${target} is alive but its pusher (pid ${marker.pid}) is gone` };
+    }
+    return { state: "live" };
+  }
+
+  /**
+   * Reap pushers whose pane has gone, and say which ones could not be judged.
+   *
+   * `unprobeable` is NOT a residual list nobody reads — it is the distinction
+   * PRODUCTION_ROADMAP Phase 5.3 requires between "dead" and "cannot probe".
+   * An agent whose liveness is unknown is left alone and reported, never reaped.
+   */
+  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 === "unknown") {
+        unprobeable.push(marker.agentId);
+        continue;
+      }
+      if (live.state === "live") continue;
+      if (this.#host.killPusher(marker)) reaped.push(marker.agentId);
+      else unprobeable.push(marker.agentId);
+    }
+    return { reaped, unprobeable };
+  }
+}

package/src/transports/types.ts

@@ -0,0 +1,201 @@
+/**
+ * THE TRANSPORT SEAM (Phase 5.4 Task 2).
+ *
+ * This interface is DERIVED from the 12 `"tmux-push"` literals and the 7
+ * `spawnSync("tmux", …)` shell-outs that were spread across `tools/`, not
+ * designed top-down. Where the phase doc's sketch and the code disagreed, the
+ * code won — three times, each recorded below, because the gate for this task is
+ * that a running fleet cannot tell the difference.
+ *
+ * 1. `tmux-push-remote` IS A LIVE KIND. The doc's sketch had two kinds; the code
+ *    has three. `registry.ts` gives remote markers heartbeat-based liveness
+ *    because their pid is 0 on a foreign host, and `server.ts` documents the
+ *    value as the wire contract for `scripts/coord-pusher.mjs`. A union without
+ *    it silently reclassifies every remote agent as not-tmux.
+ * 2. THE MARKER HAS NINE FIELDS, NOT SIX. `scriptMtime`, `serverBuildMtime` and
+ *    `rooms` are absent from the sketch and each one closes a defect that
+ *    actually shipped. They are kept verbatim, including the rule they share:
+ *    ABSENT MEANS UNKNOWN, NEVER "ON" — the same principle as `Liveness.unknown`
+ *    below, one field deeper.
+ * 3. `target` IS ADDITIVE, NOT A RENAME. See `targetOf`.
+ */
+
+/**
+ * Every transport value that can appear in a marker on disk.
+ *
+ * Not `string`: the whole defect being fixed is code branching on a literal
+ * instead of reading the field, and a `string` discriminant cannot tell the
+ * compiler that a branch was missed. Not a two-member union either — see (1).
+ */
+export const TMUX_PUSH = "tmux-push" as const;
+export const TMUX_PUSH_REMOTE = "tmux-push-remote" as const;
+export const HERDR = "herdr" as const;
+
+export type TransportKind = typeof TMUX_PUSH | typeof TMUX_PUSH_REMOTE | typeof HERDR;
+
+export const TRANSPORT_KINDS: readonly TransportKind[] = [TMUX_PUSH, TMUX_PUSH_REMOTE, HERDR] as const;
+
+/**
+ * The tmux family. Both members are delivered by a pusher process typing into a
+ * pane; they differ in WHERE that pane is, which is why liveness splits below.
+ *
+ * THIS IS THE ONE PLACE THE TMUX LITERALS LIVE. Twelve call sites used to spell
+ * them; they now ask.
+ */
+const TMUX_KINDS = new Set<string>([TMUX_PUSH, TMUX_PUSH_REMOTE]);
+
+/** Is this marker carried by the tmux family (local OR remote)? */
+export function isTmuxKind(transport: string | undefined): boolean {
+  return transport !== undefined && TMUX_KINDS.has(transport);
+}
+
+/**
+ * Is this marker's pane on THIS host, so that a local probe means anything?
+ *
+ * The distinction every `marker.transport !== "tmux-push"` site was making by
+ * hand, with a comment explaining "remote = can't verify". Naming it stops the
+ * next person re-deriving it — and re-deriving it wrongly is how a remote agent
+ * gets reported dead because a pane that was never local did not answer.
+ */
+export function isLocallyProbeable(transport: string | undefined): boolean {
+  return transport === TMUX_PUSH;
+}
+
+/**
+ * Is liveness for this marker decided by the registry heartbeat rather than by a
+ * local pid? True only for the remote kind, whose pid is 0 on a foreign host.
+ */
+export function isRemoteTmuxKind(transport: string | undefined): boolean {
+  return transport === TMUX_PUSH_REMOTE;
+}
+
+export type TransportMarker = {
+  agentId: string;
+  transport: string;
+  pid: number;
+  /**
+   * Transport-agnostic address: a tmux pane id, later a herdr session id.
+   *
+   * ADDITIVE AND DUAL-WRITTEN, not a rename of `tmuxTarget`. Measured before
+   * choosing: every marker on the live fleet's disk carries `tmuxTarget` and
+   * none carries `target`. The phase doc asks for a read-migration and its own
+   * Rollback Plan asks for no format change until the migration is proven on a
+   * live fleet; writing both satisfies each. A marker written with `target`
+   * alone is unreadable to the code a merge-revert restores, and that failure
+   * does not degrade — it silences every lane at once.
+   */
+  target?: string;
+  /** The original field. Still written. See `target`. */
+  tmuxTarget?: string;
+  since: number;
+  /**
+   * Remote pushers run on a different machine; the local pid is meaningless,
+   * so we tag the host and use heartbeat-based liveness instead of pidAlive.
+   */
+  host?: string;
+  /**
+   * mtime of the pusher script the daemon loaded into memory at spawn time
+   * (epoch ms). When the on-disk script is upgraded but the daemon isn't
+   * restarted, doctor() compares this to the current mtime to flag a stale
+   * pusher — the class of bug that silently dropped /clear /compact in v0.8.1.
+   * Absent on markers written by older versions (treated as "unknown, skip").
+   */
+  scriptMtime?: number;
+  /**
+   * Build identity of the MCP server whose attach_agent stamped this marker.
+   * A marker stamped by a server predating the current on-disk build was
+   * written by attach/stamp logic the rebuild replaced. Absent means unknown.
+   */
+  serverBuildMtime?: number;
+  /**
+   * Does this transport carry ROOM traffic, or DMs only?
+   *
+   * ABSENT MEANS UNKNOWN, NEVER "ON". A `--no-room` pusher used to look
+   * identical to a full one, so `status` said `attached: true` while an agent
+   * sat with its room feed off — that is how a worker missed its channel
+   * traffic. A marker from an older pusher cannot tell us, and reporting an
+   * unasked question as full capability is the defect this field removes.
+   */
+  rooms?: boolean;
+};
+
+/**
+ * Read a marker's address, preferring the generic field and falling back to the
+ * tmux-specific one.
+ *
+ * This is the read half of the dual-write. Call it rather than touching either
+ * field: a consumer that reads only `tmuxTarget` goes blind the day a herdr
+ * marker appears, and one that reads only `target` is blind to every marker on
+ * disk today.
+ */
+export function targetOf(marker: Pick<TransportMarker, "target" | "tmuxTarget">): string | undefined {
+  return marker.target ?? marker.tmuxTarget;
+}
+
+/**
+ * Stamp an address into BOTH fields, so the marker is legible to the current
+ * code and to whatever a revert restores.
+ */
+export function withTarget<T extends object>(marker: T, target: string | undefined): T & { target?: string; tmuxTarget?: string } {
+  if (target === undefined) return marker;
+  return { ...marker, target, tmuxTarget: target };
+}
+
+/**
+ * THE THIRD STATE IS NOT A COURTESY, IT IS THE POINT.
+ *
+ * "Cannot probe" must stay expressible and distinct from "dead": a transport
+ * that cannot answer is not evidence of a dead agent, and collapsing the two
+ * reaps live sessions. PRODUCTION_ROADMAP Phase 5.3 states the rule; the
+ * wedged-pusher reaping in `doctor` depends on it.
+ */
+export type Liveness =
+  | { state: "live" }
+  | { state: "dead"; reason: string }
+  | { state: "unknown"; reason: string };
+
+/** Keystroke-shaped commands a transport must deliver to an interactive pane. */
+export const CONTROL_COMMANDS = ["clear", "compact", "reload-skills"] as const;
+export type ControlCommand = (typeof CONTROL_COMMANDS)[number];
+
+/**
+ * What a transport must be able to do, stated as what the call sites ask for.
+ *
+ * TWO THINGS DELIBERATELY NOT DESIGNED OUT, both established by the Task 1
+ * spike and both invisible in a type:
+ *
+ * · KEY NAMES ARE NOT PORTABLE. `ctrl+u` is accepted by herdr while `C-u` and
+ *   `ctrl-u` are rejected. `sendControl` therefore takes a ControlCommand — an
+ *   INTENT — and never a key string. A transport that received opaque key names
+ *   would mistranslate them silently, which is the one failure mode a keystroke
+ *   API cannot report.
+ * · DELIVERY IS A SECOND PROCESS, BUT ONLY FOR SOME TRANSPORTS. tmux spawns a
+ *   pusher per agent; a socket transport replaces both the pusher and the pane.
+ *   So nothing here mentions a pusher, a pid or a pane: `attach` returns a
+ *   marker and `probe` interprets one. An interface that assumed a pusher could
+ *   not host an implementation that has none.
+ */
+export interface Transport {
+  readonly kind: TransportKind;
+
+  /** Is this transport usable on this host at all? (`tmux -V` for the family.) */
+  available(): boolean;
+
+  attach(args: {
+    agentId: string;
+    target?: string;
+    includeRoom?: boolean;
+    allowlist?: string[];
+    debounceMs?: number;
+  }): Promise<TransportMarker>;
+
+  detach(agentId: string): Promise<void>;
+
+  push(marker: TransportMarker, text: string): Promise<{ delivered: boolean; error?: string }>;
+
+  probe(marker: TransportMarker): Promise<Liveness>;
+
+  sendControl(marker: TransportMarker, cmd: ControlCommand): Promise<{ ok: boolean; error?: string }>;
+
+  reapWedged(markers: TransportMarker[]): Promise<{ reaped: string[]; unprobeable: string[] }>;
+}