premanmcp 1.1.7 → 1.1.8

package/bin/agent.js

@@ -84,12 +84,13 @@ const THINK_MS = 220;
 const CLEAR_LINE = "\r\u001b[2K";
 const CLEAR_SCREEN = "\u001b[2J\u001b[H";
 
-// The alternate screen buffer: what makes a session a place rather than a
-// stretch of shell output. Entering gives it a screen of its own, so a second
-// `preman` cannot be scrolled back into the first; leaving hands back the
-// screen the shell had, untouched, the way `vim` and `htop` do.
-const ENTER_ALT = "\u001b[?1049h";
-const LEAVE_ALT = "\u001b[?1049l";
+// The alternate screen buffer is deliberately not used, and the sequences for
+// it are deliberately not defined, so that reaching for one is a decision
+// rather than an autocomplete. It gave a session a screen of its own -- a
+// second `preman` could not be scrolled back into the first -- by holding
+// exactly one screen and keeping no history, which meant a reply that ran past
+// the top of the window could not be scrolled back to either. A transcript is
+// the wrong thing to put in a buffer that forgets.
 const SHOW_CURSOR = "\u001b[?25h";
 const RELEASE_REGION = "\u001b[r";
 
@@ -217,6 +218,188 @@ export function artifactLine(artifact) {
   return url ? `${truncate(label, 72)} — ${url}` : truncate(label, 100);
 }
 
+/**
+ * The route an endpoint sits on, normalised so two saved requests that hit the
+ * same place collapse onto one line.
+ *
+ * The same rule the app groups by, deliberately: a workspace that reads as 84
+ * routes in the browser and 284 rows here is two different answers to one
+ * question. A saved URL is often a template (`{{baseUrl}}/v1/users`) rather
+ * than something `URL` will parse, which is why the fallback strips the
+ * template head by hand instead of giving up.
+ */
+export function endpointRoutePath(endpoint) {
+  const raw = String(endpoint?.url || endpoint?.name || "/").trim();
+  let path = raw;
+  try {
+    path = new URL(raw).pathname || "/";
+  } catch {
+    path = raw.replace(/^\{\{[^}]+\}\}/, "").split(/[?#]/, 1)[0] || "/";
+  }
+  if (!path.startsWith("/")) path = `/${path}`;
+  return path.length > 1 ? path.replace(/\/+$/, "") : path;
+}
+
+// The three buckets the server counts in and the model writes its reply from.
+// Matching them exactly is what keeps "87 failing" in the prose and the heading
+// above the rows from being two different numbers.
+const FAILING_RUNS = new Set(["failed", "error", "fail"]);
+const PASSING_RUNS = new Set(["passed", "pass", "ok", "success"]);
+
+/** Which of the three buckets a last-run status falls in. */
+export function endpointBucket(lastRun) {
+  const status = String(lastRun || "").trim().toLowerCase();
+  if (!status) return "untested";
+  if (FAILING_RUNS.has(status)) return "failing";
+  if (PASSING_RUNS.has(status)) return "passing";
+  return "untested";
+}
+
+// Failing first because it is the only bucket anybody acts on, then untested,
+// then passing -- the order the model already writes its own summary in.
+const BUCKET_ORDER = ["failing", "untested", "passing"];
+const BUCKET_LABELS = { failing: "Failing", untested: "Untested", passing: "Passing" };
+const METHOD_ORDER = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+
+const methodRank = (method) => {
+  const at = METHOD_ORDER.indexOf(String(method || "GET").trim().toUpperCase());
+  return at === -1 ? METHOD_ORDER.length : at;
+};
+
+/**
+ * Every endpoint the turn returned, once, as routes.
+ *
+ * A list of 284 arrives as thirteen separate tool calls, because the tool caps
+ * a page at 25 rows and the model pages through it. Ids are deduplicated
+ * because overlapping pages are a model's decision and not a thing to render
+ * twice; routes are collapsed because that is what turns request history back
+ * into an API. A route whose saved requests disagree about their last run
+ * takes the worst of them, since "one of these is failing" is the fact worth
+ * putting on a line somebody is scanning for failures.
+ */
+export function mergeEndpoints(artifacts = []) {
+  const seen = new Set();
+  const endpoints = [];
+  // The furthest page reached in each sweep the model made. A turn that lists
+  // everything is several sweeps -- one per status -- and every page but the
+  // last of each carries has_more, so believing all of them would claim the
+  // catalogue was cut short on exactly the turns that read all of it.
+  const sweeps = new Map();
+  let saved = 0;
+
+  for (const artifact of artifacts) {
+    saved = Math.max(saved, Number(artifact?.total_count) || 0);
+    const key = `${artifact?.status ?? ""}|${artifact?.query ?? ""}`;
+    const offset = Number(artifact?.offset) || 0;
+    const reached = offset + (artifact?.endpoints?.length || 0);
+    const furthest = sweeps.get(key);
+    if (!furthest || offset >= furthest.offset) {
+      sweeps.set(key, {
+        offset,
+        more: Boolean(artifact?.has_more) || (Number(artifact?.matched_count) || 0) > reached,
+      });
+    }
+    for (const endpoint of artifact?.endpoints || []) {
+      const id = String(endpoint?.id ?? "");
+      if (id && seen.has(id)) continue;
+      if (id) seen.add(id);
+      endpoints.push(endpoint);
+    }
+  }
+
+  const routes = new Map();
+  const counts = { failing: 0, untested: 0, passing: 0 };
+  for (const endpoint of endpoints) {
+    const method = String(endpoint?.method || "GET").trim().toUpperCase();
+    const path = endpointRoutePath(endpoint);
+    const bucket = endpointBucket(endpoint?.last_run);
+    counts[bucket] += 1;
+    const key = `${method} ${path}`;
+    const found = routes.get(key);
+    if (!found) {
+      routes.set(key, { method, path, bucket, count: 1 });
+      continue;
+    }
+    found.count += 1;
+    if (BUCKET_ORDER.indexOf(bucket) < BUCKET_ORDER.indexOf(found.bucket)) found.bucket = bucket;
+  }
+
+  const ordered = [...routes.values()].sort(
+    (left, right) => methodRank(left.method) - methodRank(right.method) || left.path.localeCompare(right.path)
+  );
+  return { endpoints, routes: ordered, counts, saved, more: [...sweeps.values()].some((s) => s.more) };
+}
+
+/**
+ * The endpoints of a turn, drawn for a terminal.
+ *
+ * Until now this surface printed the artifact's title and dropped its payload,
+ * so a request to list 284 endpoints produced thirteen lines reading "showing
+ * 51-75 of 197" and not one endpoint. The model's reply said the list was
+ * above, and in the app it is -- the card renders the rows. Here there is no
+ * card and no page to send anybody to: the transcript is the whole surface, so
+ * the rows have to land in it.
+ *
+ * Piped output is a different contract and gets a different shape: one line per
+ * endpoint, ungrouped and never truncated, because on the other end of a pipe
+ * this is something being grepped rather than read.
+ */
+export function endpointsBlock(artifacts, { columns = 80, live = true, paint } = {}) {
+  const ink = paint || makePaint(false);
+  const { endpoints, routes, counts, saved, more } = mergeEndpoints(artifacts);
+  if (!endpoints.length) return "";
+
+  if (!live) {
+    const lines = endpoints.map((endpoint) => {
+      const method = String(endpoint?.method || "GET").trim().toUpperCase();
+      const where = String(endpoint?.url || "").trim() || endpointRoutePath(endpoint);
+      return `  ${endpointBucket(endpoint?.last_run).padEnd(8)} ${method.padEnd(7)} ${where}`;
+    });
+    return `${lines.join("\n")}\n`;
+  }
+
+  const shown = endpoints.length;
+  const head = [`${shown} endpoint${shown === 1 ? "" : "s"}`];
+  if (saved > shown) head[0] = `${shown} of ${saved} endpoints`;
+  if (routes.length !== shown) head.push(`${routes.length} route${routes.length === 1 ? "" : "s"}`);
+  for (const bucket of BUCKET_ORDER) {
+    if (counts[bucket]) head.push(`${counts[bucket]} ${bucket}`);
+  }
+
+  const width = Math.max(24, columns);
+  // Truncated before it is painted, not after: the colour runs are bytes that
+  // `truncate` would count and cut through, and half an escape sequence on a
+  // narrow window is a terminal left in the wrong colour.
+  const lines = [
+    `  ${ink.bold("Endpoints")} ${ink.dim(`\u00b7 ${truncate(head.join(" \u00b7 "), Math.max(8, width - 14))}`)}`,
+  ];
+  const method = Math.min(7, Math.max(...routes.map((route) => route.method.length)));
+  const room = Math.max(8, width - 6 - method - 2);
+
+  for (const bucket of BUCKET_ORDER) {
+    const group = routes.filter((route) => route.bucket === bucket);
+    if (!group.length) continue;
+    lines.push("", `  ${ink.bold(BUCKET_LABELS[bucket])} ${ink.dim(`(${counts[bucket]})`)}`);
+    for (const route of group) {
+      // A hollow mark for untested, because "no run yet" is an absence rather
+      // than a result, and a filled dot in any colour reads as one.
+      const dot =
+        bucket === "failing" ? ink.red("\u25cf") : bucket === "passing" ? ink.green("\u25cf") : ink.dim("\u25cb");
+      const also = route.count > 1 ? ink.dim(` (${route.count})`) : "";
+      lines.push(`    ${dot} ${ink.dim(route.method.padEnd(method))}  ${truncate(route.path, room)}${also}`);
+    }
+  }
+
+  // Said once, at the end, rather than thirteen times on the way: the model
+  // stopped paging before the catalogue ran out, and the rest is a command
+  // away rather than a page in a browser this session cannot open.
+  if (more) {
+    const rest = `More were not fetched. ${cliInvocation()} endpoints list for the rest.`;
+    lines.push("", `  ${ink.dim(truncate(rest, width - 2))}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
 /** The permission questions in a finished turn, in the order they were asked. */
 export function permissionQuestions(artifacts = []) {
   return (Array.isArray(artifacts) ? artifacts : []).filter(
@@ -268,6 +451,13 @@ function makePaint(enabled) {
  */
 export function createRenderer({ stream = process.stdout, paint, live } = {}) {
   const isLive = live ?? Boolean(stream.isTTY);
+  // Whether there is a window here, which is a different question from whether
+  // it may be coloured. `NO_COLOR=1` is a widespread way of saying "no colour",
+  // and it used to reach layout as "this is a pipe" -- so somebody who set it
+  // and sat down at a terminal got the shape meant for `grep`. Colour is the
+  // palette's business; how wide the window is and whether rows may be grouped
+  // and clipped is this.
+  const isTerminal = Boolean(stream.isTTY);
   const ink = paint || makePaint(isLive);
   let timer = null;
   let frame = 0;
@@ -277,6 +467,8 @@ export function createRenderer({ stream = process.stdout, paint, live } = {}) {
   let stallTick = 0;
   let wroteReply = false;
   let atLineStart = true;
+  // Endpoint pages, held until the turn has something else to say.
+  let pages = [];
 
   function stopStall() {
     if (!stall) return false;
@@ -312,6 +504,26 @@ export function createRenderer({ stream = process.stdout, paint, live } = {}) {
     stream.write(`${CLEAR_LINE}${tint(`${word}${runOn} ${dots}`)}`);
   }
 
+  /**
+   * Draw the endpoint pages collected so far, as one table.
+   *
+   * Held rather than printed on arrival because a single "list my endpoints"
+   * is thirteen tool calls, and thirteen tables of 25 rows is not a list --
+   * it is the pagination read aloud. Flushed by whatever speaks next, so the
+   * rows still land *above* the reply that refers to them.
+   */
+  function flushPages() {
+    if (!pages.length) return;
+    const held = pages;
+    pages = [];
+    const block = endpointsBlock(held, { columns: stream.columns || 80, live: isTerminal, paint: ink });
+    if (!block) return;
+    clearSpinner();
+    if (!atLineStart) stream.write("\n");
+    stream.write(block);
+    atLineStart = true;
+  }
+
   function draw() {
     if (!isLive || !label) return;
     const spin = FRAMES[frame % FRAMES.length];
@@ -347,8 +559,16 @@ export function createRenderer({ stream = process.stdout, paint, live } = {}) {
       }
     },
     artifact(item) {
+      // Endpoint pages are the one artifact whose payload is the point, and
+      // they arrive one page at a time, so they are collected rather than
+      // drawn. Everything else is a card this surface summarises in a line.
+      if (item && item.type === "endpoints" && Array.isArray(item.endpoints)) {
+        pages.push(item);
+        return;
+      }
       const line = artifactLine(item);
       if (!line) return;
+      flushPages();
       clearSpinner();
       if (!atLineStart) stream.write("\n");
       stream.write(`  ${ink.cyan("●")} ${line}\n`);
@@ -357,6 +577,7 @@ export function createRenderer({ stream = process.stdout, paint, live } = {}) {
     delta(text) {
       const chunk = String(text ?? "");
       if (!chunk) return;
+      flushPages();
       clearSpinner();
       if (!wroteReply) {
         stream.write("\n");
@@ -373,18 +594,23 @@ export function createRenderer({ stream = process.stdout, paint, live } = {}) {
       this.delta(body);
     },
     note(text) {
+      flushPages();
       clearSpinner();
       if (!atLineStart) stream.write("\n");
       stream.write(`${ink.dim(String(text))}\n`);
       atLineStart = true;
     },
     error(text) {
+      flushPages();
       clearSpinner();
       if (!atLineStart) stream.write("\n");
       stream.write(`${ink.red(String(text))}\n`);
       atLineStart = true;
     },
     end() {
+      // The backstop: a turn that listed endpoints and then said nothing at
+      // all still has to put them on the screen.
+      flushPages();
       clearSpinner();
       if (!atLineStart) stream.write("\n");
       if (wroteReply) stream.write("\n");
@@ -705,7 +931,14 @@ export function holdTerminal({ stream = process.stdout, footer = () => "" } = {}
     if (restored) return;
     restored = true;
     for (const fn of teardown.splice(0)) safely(fn);
-    if (live) safely(() => stream.write(`${RELEASE_REGION}${LEAVE_ALT}${SHOW_CURSOR}${CLEAR_TITLE}`));
+    // No `ESC[?1049l` here any more, and its absence is load-bearing rather
+    // than tidying. The session never enters the alternate screen, so leaving
+    // it would be addressed to a buffer nobody is on -- and the sequence is
+    // not inert: it restores the cursor as DECRC does, from the same saved
+    // slot the dock writes the transcript's position into with `ESC7`. Sent on
+    // the shell's own screen it would drag the cursor back up into the
+    // transcript and print the resume footer over the conversation.
+    if (live) safely(() => stream.write(`${RELEASE_REGION}${SHOW_CURSOR}${CLEAR_TITLE}`));
     safely(() => {
       const text = footer();
       if (text) stream.write(text);
@@ -1236,7 +1469,32 @@ export function createDock({
       at = null;
       const { rows } = size();
       stream.write("\u001b[r");
-      stream.write(`\u001b[${rows};1H\u001b[2K`);
+      // Every row the furniture owned, not just the last one. On the alternate
+      // screen clearing one row was enough because leaving the buffer threw the
+      // whole screen away; on the shell's own screen the chrome is real output,
+      // and a composer box and a status strip left sitting under the final
+      // prompt are the last thing the session shows.
+      //
+      // Guarded on having painted, because that is the only thing that says
+      // these rows were ever the dock's. In a window too short to dock in
+      // nothing is drawn at all -- the session is a plain prompt -- and erasing
+      // four rows of a five-row window there would take somebody's transcript
+      // with it. Clamped to the live window for the same reason `resize` is:
+      // after a shrink, `painted.rows` names rows that no longer exist.
+      if (painted) {
+        const bottom = Math.min(painted.rows, rows);
+        const top = Math.max(1, bottom - DOCK_ROWS + 1);
+        for (let row = top; row <= bottom; row += 1) {
+          stream.write(`\u001b[${row};1H\u001b[2K`);
+        }
+        // Carry on immediately below the transcript rather than at the bottom
+        // of the window, so the resume footer and the shell prompt follow the
+        // conversation instead of a gap where the dock used to be.
+        stream.write(`\u001b[${top};1H`);
+      } else {
+        stream.write(`\u001b[${rows};1H\u001b[2K`);
+      }
+      painted = null;
       stream.write(CLEAR_TITLE);
     },
   };
@@ -1738,10 +1996,27 @@ export async function agentCommand(commandArgs = [], { authenticate = authentica
     if (args.has("--print") || args.has("-p") || !process.stdin.isTTY) return;
   }
 
-  // The session's own screen, entered before anything is printed so the banner
-  // lands at the top of it. A terminal that does not understand the sequence
-  // ignores it and gets exactly what it got before.
-  const fullScreen = Boolean(process.stdout.isTTY);
+  // The session shares the shell's screen rather than taking one of its own.
+  //
+  // It used to enter the alternate screen, the way a full-screen app does, and
+  // that cost the one thing a chat transcript needs: the alternate buffer keeps
+  // no history, so a reply that ran past the top of the window was not scrolled
+  // away, it was discarded. There was nothing to scroll back to in any
+  // terminal, because the buffer holds exactly one screen.
+  //
+  // On the shell's own screen the transcript is ordinary output, so the wheel,
+  // Page Up, find and select-to-copy all work on a conversation the way they
+  // work on any other command's output. Keeping the composer docked costs none
+  // of it: the dock's scrolling region starts at row 1, and a region whose top
+  // margin is the first row is the case where a terminal pushes the lines it
+  // scrolls past into the scrollback instead of dropping them.
+  //
+  // What this gives up is what the alternate screen was for -- a new session
+  // can now be scrolled back into a finished one. That is the trade every
+  // other command makes with its own output, and it is the cheaper way round:
+  // scrolling into an old session is something a reader can see and scroll out
+  // of, and a transcript that cannot be scrolled at all is not.
+  const interactive = Boolean(process.stdout.isTTY);
 
   // Watching before the screen is taken, not after: the handlers have to be up
   // for every moment the terminal is in a state somebody else has to live with.
@@ -1755,13 +2030,11 @@ export async function agentCommand(commandArgs = [], { authenticate = authentica
       // A conversation whose id never arrived stringifies to "undefined", and a
       // resume line naming that is worse than no resume line.
       const id = String(conversation?.id || "");
-      if (!fullScreen || !id || id === "undefined") return "";
+      if (!interactive || !id || id === "undefined") return "";
       return `${paint.dim("Resume this session with:")}\n  ${cliInvocation()} --conversation ${id}\n`;
     },
   }).watch();
 
-  if (fullScreen) process.stdout.write(`${ENTER_ALT}${CLEAR_SCREEN}`);
-
   const dock = createDock({
     stream: process.stdout,
     paint,
@@ -1770,13 +2043,13 @@ export async function agentCommand(commandArgs = [], { authenticate = authentica
   const prompt = `${paint.caret("\u276f")} `;
   const rl = createInterface({ input: process.stdin, output: process.stdout, prompt });
   dock.attach(rl);
-  // The screen was just cleared, so the transcript starts at the top of it and
-  // the dock is told so. The banner then goes through the dock rather than
-  // around it, which is what keeps the two in step: printing it to stdout first
-  // and docking afterwards left the transcript anchored at the bottom of the
-  // window, eleven blank rows below a banner that the first line of the first
-  // reply then scrolled a row closer to the top.
-  dock.enable(fullScreen ? { row: 1 } : undefined);
+  // No start row, because there is no cleared screen to start at the top of any
+  // more. Told nothing, the dock makes room by scrolling the shell up by its
+  // own height and carries on at the floor -- which keeps whatever was on the
+  // screen before, the prompt the session was launched from included, instead
+  // of erasing it. The banner still goes through the dock rather than around
+  // it, which is what keeps the two in step.
+  dock.enable();
 
   dock.write(banner({ paint, workspace, backend: backendUrl(args), conversation }));
   const onResize = () => dock.resize();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "description": "PreMan CLI and stdio proxy for PreMan's hosted MCP server",
   "type": "module",
   "bin": {