/**
 * ⟨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}` };
  }
}