agent-coord-mcp 0.26.19 → 0.26.21

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[] }>;
+}