agent-coord-mcp 0.26.31 → 0.26.33

package/src/tools/pane.ts

@@ -0,0 +1,49 @@
+/**
+ * ⟨q-927e28cd⟩ ADR-023 d4, NARROW SLICE — A CONSUMER READS A SEAT'S PANE THROUGH THE BUS.
+ *
+ * The console showed every herdr seat's pane as `410 "pane not found (session gone?)"` for a
+ * live seat, because it captured panes itself through tmux and a herdr pane is not a tmux
+ * pane. ADR-023 d4 says a consumer asks the bus rather than learning each transport; this is
+ * the one question it could not ask, because no bus verb returned what a pane shows.
+ *
+ * ⛔ READ THROUGH THE TRANSPORT, NEVER AROUND IT (the coordinator's GO, and ADR-023 d1). This
+ * module names no field of the marker: it hands the whole marker to `Transport.readPane`,
+ * which decides which pane it is, whether it is its own kind, and whether it is still there.
+ * qa counted 47 marker-internal reads across 5 modules outside src/transports/; this is not
+ * the 48th, and a test says so by reading this file.
+ *
+ * ⛔ READ-ONLY, INCLUDING OF THE STATE DIR. `loadLiveTransports` deletes markers it judges
+ * dead, which is a write; this reads the one marker file and deletes nothing. Whether the
+ * pane is gone is the transport's answer, and it answers UNKNOWN, never an empty screen.
+ */
+import { z } from "zod";
+import type { PaneRead, Transport, TransportMarker } from "../transports/types.js";
+import { activeTransport } from "../transports/index.js";
+import { readJson, transportFile } from "../store.js";
+
+export const readPaneSchema = {
+  agentId: z.string().min(1),
+  /** The seat whose pane to read. */
+  targetAgentId: z.string().min(1),
+  lines: z.number().int().positive().max(2000).optional(),
+  /** Keep the terminal's styling (ANSI escapes) rather than plain text. */
+  colors: z.boolean().optional(),
+};
+
+export type ReadPaneResult = { ok: true; agentId: string } & PaneRead;
+
+export async function readPaneTool(
+  args: { agentId: string; targetAgentId: string; lines?: number; colors?: boolean },
+  transport: Transport | null | undefined = activeTransport(),
+): Promise<ReadPaneResult> {
+  const agentId = args.targetAgentId;
+  const marker = await readJson<TransportMarker | null>(transportFile(agentId), null);
+  if (!marker) return { ok: true, agentId, state: "unknown", why: "no transport marker — the seat is not attached, so there is no pane on record to read" };
+  if (!transport) return { ok: true, agentId, state: "unknown", why: "no transport is wired in this server process, so nothing can read a pane" };
+  if (typeof transport.readPane !== "function") return { ok: true, agentId, state: "unknown", why: `the ${transport.kind} transport cannot read a pane from this host` };
+  try {
+    return { ok: true, agentId, ...(await transport.readPane(marker, { lines: args.lines, format: args.colors ? "ansi" : "text" })) };
+  } catch (e) {
+    return { ok: true, agentId, state: "unknown", why: `the transport threw while reading the pane: ${(e as Error).message}` };
+  }
+}

package/src/transports/herdr.ts

@@ -34,7 +34,7 @@
  *     same reason (identical evidence for a typo and a default).
  */
 import { spawnSync } from "node:child_process";
-import type { ControlCommand, Liveness, Transport, TransportKind, TransportMarker, TickReading, TickState } from "./types.js";
+import type { ControlCommand, Liveness, PaneRead, Transport, TransportKind, TransportMarker, TickReading, TickState } from "./types.js";
 import { HERDR, TICK_READS_AS, TICK_STORED_AS, targetOf } from "./types.js";
 // ⟨q-dc83023a⟩ The chip grammar and the pane-unsafe byte class are single-sourced in hooks/, shared
 // with both pushers. `hooks/` ships beside `dist/`, so these resolve the same when installed.
@@ -587,6 +587,33 @@ export class HerdrTransport implements Transport {
     return { readable: false, why: `herdr reports agent_status "${status}" for pane ${target} — no agent state is published there, which is a MISSING signal, not a calm seat` };
   }
 
+  /**
+   * ⟨q-927e28cd⟩ THE SCREEN, FOR A CONSUMER — herdr's own `pane read`, the same read `push`
+   * verifies with. Same guards, in the same order, as `readTick`: a marker that is not herdr's,
+   * one with no target, or herdr absent answers UNKNOWN naming which; a pane herdr cannot find
+   * is UNKNOWN too — it is gone, and a gone pane has no screen, not an empty one.
+   */
+  async readPane(marker: TransportMarker, opts: { lines?: number; format?: "text" | "ansi" } = {}): Promise<PaneRead> {
+    return this.readPaneNow(marker, opts);
+  }
+
+  /** The whole rule, synchronous — `readPane` and the capabilities probe both call THIS, so the probe cannot pass while the verb behaves differently. */
+  readPaneNow(marker: TransportMarker, opts: { lines?: number; format?: "text" | "ansi" } = {}): PaneRead {
+    if (marker.transport !== HERDR) return { state: "unknown", why: `transport "${marker.transport}" is not herdr — this transport reads only its own panes` };
+    const target = targetOf(marker);
+    if (!target) return { state: "unknown", why: "no target recorded on the marker" };
+    const avail = this.availability();
+    if (!avail.available) return { state: "unknown", why: avail.reason };
+    const lines = Math.min(Math.max(Math.trunc(opts.lines ?? 200), 1), 2000);
+    const format = opts.format === "ansi" ? "ansi" : "text";
+    const read = this.#run(["pane", "read", target, "--source", "visible", "--lines", String(lines), "--format", format]);
+    if (!read.ok) {
+      if (read.error?.code === "pane_not_found") return { state: "unknown", why: `herdr reports pane ${target} not found — a gone pane has no screen to read` };
+      return { state: "unknown", why: `herdr could not read pane ${target}: ${read.error?.message ?? read.stderr}` };
+    }
+    return { state: "read", text: read.stdout, lines, format, source: `herdr pane ${target}` };
+  }
+
   /**
    * ⟨q-1c95f7d4⟩ Task 1's open question — PUBLISH, and it needs a receipt it does not get.
    *

package/src/transports/types.ts

@@ -249,6 +249,18 @@ export type TickReading =
   | { readable: true; state: TickState; source: string }
   | { readable: false; why: string };
 
+/**
+ * ⟨q-927e28cd⟩ ADR-023 d4, narrow slice — WHAT A PANE SHOWS, READ THROUGH THE TRANSPORT.
+ *
+ * Two answers and no third: the screen, or UNKNOWN with the reason. A pane that is gone, a
+ * binary that is absent, a marker of another kind — each is `unknown`, never an empty screen
+ * and never a stale one: an empty string would read as "the seat is showing nothing", which
+ * is a claim about the seat that nothing measured.
+ */
+export type PaneRead =
+  | { state: "read"; text: string; lines: number; format: "text" | "ansi"; source: string }
+  | { state: "unknown"; why: 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];
@@ -313,6 +325,18 @@ export interface Transport {
    */
   publishTick?(marker: TransportMarker, state: TickState, opts?: { message?: string; source?: string }): Promise<{ ok: boolean; error?: string }>;
 
+  /**
+   * ⟨q-927e28cd⟩ OPTIONAL, AND ITS ABSENCE IS AN ANSWER: a transport that cannot see the
+   * seat's screen from this host (tmux-push-remote: the pane is on another machine) does not
+   * implement it, and every caller reports `unknown` for it rather than guessing.
+   *
+   * ⛔ THE ONE PLACE A PANE IS READ FOR A CONSUMER. Callers pass the WHOLE marker and read no
+   * field of it — which pane, which kind, whether it is this transport's to read are all
+   * decided in here (ADR-023 d1). A caller that needed `target` to use this would be the
+   * forty-eighth marker-internal read qa counted outside src/transports/.
+   */
+  readPane?(marker: TransportMarker, opts?: { lines?: number; format?: "text" | "ansi" }): Promise<PaneRead>;
+
   /**
    * ⟨q-ec020f6a⟩(A) — OPTIONAL, and its absence is the honest answer for tmux (a pane's live
    * "session" concept is a herdr feature; tmux has no equivalent to re-check). Declaring the