pi-link 0.3.0 → 0.4.0

package/bin/pi-link.mjs

@@ -6,6 +6,7 @@
 //   pi-link <name> [--global|-g] [flags...]
 //                                Resume or create a named session, connected to link.
 //   pi-link --list [--global|-g] List pi-link sessions in current cwd (or everywhere).
+//   pi-link --status [--json]   Show terminals connected to the running hub right now.
 //   pi-link --resolve <name> [--global|-g]
 //                                Print just the session path (machine-readable).
 //   pi-link --version            Print the installed pi-link version.
@@ -151,6 +152,11 @@ const useAnsi =
 const bold = (s) => (useAnsi ? `\x1b[1m${s}\x1b[22m` : s);
 const dim = (s) => (useAnsi ? `\x1b[2m${s}\x1b[22m` : s);
 
+// What `--status` prints for a field the hub could not report. Declared here,
+// above the dispatcher: the mode handlers are hoisted functions, but a `const`
+// read from one would still be in its temporal dead zone when dispatch runs.
+const UNKNOWN = "?";
+
 function relTime(d) {
   const sec = Math.max(0, Math.floor((Date.now() - d.getTime()) / 1000));
   if (sec < 60) return `${sec}s ago`;
@@ -299,11 +305,13 @@ function fail(msg) {
 function printHelp() {
   console.error("Usage: pi-link <name> [--global|-g] [pi flags...]");
   console.error("       pi-link --list [--global|-g]");
+  console.error("       pi-link --status [--json]");
   console.error("       pi-link --resolve <name> [--global|-g]");
   console.error("       pi-link --version");
   console.error("");
   console.error("By default, name lookup is scoped to the current cwd.");
   console.error("--global / -g widens the search to sessions in any cwd.");
+  console.error("--list reads saved sessions; --status asks the running hub who is connected.");
 }
 
 function printVersion() {
@@ -322,6 +330,7 @@ function describeMode(mode) {
     case "help": return "--help";
     case "version": return "--version";
     case "list": return "--list";
+    case "status": return "--status";
     case "resolve": return "--resolve";
     case "launcher": return "session name";
     default: return mode;
@@ -338,10 +347,11 @@ function describeMode(mode) {
 //   5. Launcher passthrough (mode launcher) with orphan-positional rejection
 
 const state = {
-  mode: null, // null | "help" | "version" | "list" | "resolve" | "launcher"
+  mode: null, // null | "help" | "version" | "list" | "status" | "resolve" | "launcher"
   resolveName: null,
   launcherName: null,
   global: false,
+  json: false,
   piPassthrough: [],
 };
 
@@ -383,11 +393,25 @@ for (let i = 0; i < rawArgs.length; i++) {
     break;
   }
 
+  // `--json` modifies --status only. Claimed before a mode exists so order does
+  // not matter, but never in launcher mode, where it belongs to pi.
+  if (a === "--json" && (state.mode === null || state.mode === "status")) {
+    state.json = true;
+    continue;
+  }
+
   // Phase 2: mode-selecting flags.
   if (a === "--list") {
     setMode("list");
     continue;
   }
+  // Selects the wrapper's own mode only before a session name has been seen.
+  // After that it is pi's flag, exactly like `--json` above — intercepting it
+  // unconditionally would break `pi-link foo --status`.
+  if (a === "--status" && state.mode !== "launcher") {
+    setMode("status");
+    continue;
+  }
   if (a.startsWith("--resolve=")) {
     setMode("resolve");
     if (state.resolveName !== null) fail(`--resolve specified more than once`);
@@ -416,6 +440,9 @@ for (let i = 0; i < rawArgs.length; i++) {
   if (state.mode === "list") {
     fail(`--list does not accept argument: ${a}\n  Usage: pi-link --list [--global|-g]`);
   }
+  if (state.mode === "status") {
+    fail(`--status does not accept arguments: ${a}\n  Usage: pi-link --status [--json]`);
+  }
   if (state.mode === "resolve") {
     fail(`--resolve accepts exactly one name; got extra: ${a}`);
   }
@@ -465,6 +492,14 @@ if (state.mode === "resolve") {
   }
   state.resolveName = normalized;
 }
+// `--status` reads one running hub, so a cwd scope is meaningless rather than
+// merely unused: silently ignoring `-g` would imply a filter that cannot exist.
+if (state.mode === "status" && state.global) {
+  fail(`cannot combine --status and --global`);
+}
+if (state.json && state.mode !== "status") {
+  fail(`--json is only valid with --status`);
+}
 if (state.mode === "launcher") {
   const normalized = normalizeName(state.launcherName);
   if (!normalized) {
@@ -488,6 +523,9 @@ switch (state.mode) {
   case "list":
     await runList(state);
     break;
+  case "status":
+    await runStatus(state);
+    break;
   case "resolve":
     await runResolve(state);
     break;
@@ -534,6 +572,145 @@ async function runList(state) {
   }
 }
 
+// ── Status (live hub query) ────────────────────────────────────────────────
+//
+// `--list` reads saved history; `--status` asks the hub who is connected now.
+// The two answer different questions, so they share no code path.
+
+// Mirrors the extension's formatTokens so both renderings of one number agree.
+function formatTokens(n) {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${Math.round(n / 1000)}K`;
+  return `${n}`;
+}
+
+// `92K/272K (34%)`, or `?/272K` when the hub has a window but no token count.
+// Only reached for a validated payload, so `c` is null or a well-typed snapshot;
+// a non-positive window is still possible and still means nothing to report.
+function formatContext(c) {
+  if (!c || c.window <= 0) return UNKNOWN;
+  const window = formatTokens(c.window);
+  if (typeof c.tokens !== "number") return `${UNKNOWN}/${window}`;
+  return `${formatTokens(c.tokens)}/${window} (${Math.round((c.tokens / c.window) * 100)}%)`;
+}
+
+function formatAge(seconds) {
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+  return `${Math.floor(seconds / 3600)}h`;
+}
+
+// `status` and `sinceSeconds` are an optional pair: the hub omits them for a
+// terminal it has registered but not yet heard from. Absence means unknown, so
+// it must render as unknown — printing `idle` there would be an invention, and
+// acting on it is the misreporting this command exists to end.
+function formatTerminalStatus(entry) {
+  if (typeof entry.status !== "string") return UNKNOWN;
+  return `${entry.status} (${formatAge(entry.sinceSeconds)})`;
+}
+
+function failUnsupported() {
+  console.error("Link hub does not support /status \u2014 update pi-link and restart terminals.");
+  process.exit(1);
+}
+
+function failNoHub(port) {
+  console.error(`No link hub running on :${port}.`);
+  process.exit(2);
+}
+
+// The frozen contract, checked before any field is read. Anything else on the
+// port — a different service, a newer hub, a truncated proxy — must produce the
+// unsupported message, never a stack trace. Unknown extra fields stay allowed.
+function isContextField(c) {
+  if (c === null) return true;
+  if (!c || typeof c !== "object") return false;
+  return (c.tokens === null || typeof c.tokens === "number") && typeof c.window === "number";
+}
+
+function isTerminalEntry(entry, index) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
+  if (typeof entry.name !== "string") return false;
+  // Hub first, then clients — the ordering the renderer relies on.
+  if (entry.role !== (index === 0 ? "hub" : "client")) return false;
+  // `status` and `sinceSeconds` are one optional pair: both or neither.
+  //
+  // The value is checked for shape, not vocabulary. `idle`/`thinking`/
+  // `compacting`/`tool:<name>` are today's kinds, but that set has already grown
+  // once (`compacting` arrived after 0.3.0) and the CLI never branches on it — it
+  // only prints it. Freezing the list here would make a newer hub's fifth kind
+  // reject the whole payload, and only while some terminal happened to be in that
+  // state: an intermittent failure telling the user to update. An empty string is
+  // still rejected, because it renders as a blank cell with a bare duration.
+  const hasStatus = "status" in entry;
+  if (hasStatus !== ("sinceSeconds" in entry)) return false;
+  if (hasStatus && (typeof entry.status !== "string" || entry.status === "" || typeof entry.sinceSeconds !== "number")) {
+    return false;
+  }
+  if ("cwd" in entry && typeof entry.cwd !== "string") return false;
+  return "context" in entry && isContextField(entry.context);
+}
+
+function isStatusPayload(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
+  if (typeof payload.hub !== "string" || typeof payload.port !== "number") return false;
+  // A hub always reports itself, so an empty list is not this contract.
+  if (!Array.isArray(payload.terminals) || payload.terminals.length === 0) return false;
+  if (!payload.terminals.every(isTerminalEntry)) return false;
+  return payload.terminals[0].name === payload.hub;
+}
+
+async function runStatus(state) {
+  // Deliberately unvalidated: a bad value fails the fetch and is reported with
+  // the port in the message, which is the diagnosis.
+  const port = process.env.PI_LINK_PORT ?? 9900;
+  // One deadline covers the whole exchange, headers and body alike, so it has to
+  // be readable afterwards to tell a timeout from a malformed answer.
+  const deadline = AbortSignal.timeout(2000);
+  let response;
+  try {
+    response = await fetch(`http://127.0.0.1:${port}/status`, { signal: deadline });
+  } catch {
+    // Refused, unreachable or timed out: no hub is answering at this instant.
+    failNoHub(port);
+  }
+
+  if (!response.ok) failUnsupported();
+
+  let body;
+  try {
+    body = await response.text();
+  } catch {
+    // A listener that sends headers and then stalls is still an unanswered
+    // query, not an old hub: every timeout reports as "no hub".
+    if (deadline.aborted) failNoHub(port);
+    failUnsupported();
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(body);
+  } catch {
+    failUnsupported();
+  }
+  if (!isStatusPayload(payload)) failUnsupported();
+
+  if (state.json) {
+    process.stdout.write(body);
+    return;
+  }
+
+  // Payload order is meaningful: the hub is first, then clients sorted by name.
+  console.log(
+    renderTable(payload.terminals, [
+      { header: "NAME", get: (e) => e.name },
+      { header: "STATUS", get: (e) => formatTerminalStatus(e) },
+      { header: "CONTEXT", get: (e) => formatContext(e.context) },
+      { header: "CWD", get: (e) => (e.cwd ? displayPath(e.cwd) : UNKNOWN), dim: true },
+    ]),
+  );
+}
+
 async function runResolve(state) {
   const name = state.resolveName; // already normalized
   const { dir, isCustom } = resolveSessionDir(process.cwd(), resolveAgentDir());

package/index.ts

@@ -18,6 +18,7 @@ import {
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import * as crypto from "node:crypto";
+import { createServer, type Server as HttpServer } from "node:http";
 import * as os from "node:os";
 
 import { WebSocket, WebSocketServer } from "ws";
@@ -209,6 +210,9 @@ export default function (pi: ExtensionAPI) {
 
   // Hub state
   let wss: WebSocketServer | null = null;
+  // The hub owns the HTTP server the WS server rides on, because `wss.close()`
+  // never closes a server it was handed. Nulled wherever `wss` is.
+  let hubHttpServer: HttpServer | null = null;
   const hubClients = new Map<WebSocket, string>(); // ws → terminal name
   const hubTerminalStatuses = new Map<string, LinkStatus>(); // hub-authoritative
   const hubTerminalContexts = new Map<string, ContextSnapshot>(); // hub-authoritative
@@ -226,6 +230,7 @@ export default function (pi: ExtensionAPI) {
     promise: Promise<void>;
     socket: WebSocket | null; // dialing, not yet `ws`
     server: WebSocketServer | null; // binding, not yet `wss`
+    httpServer: HttpServer | null; // binding, not yet `hubHttpServer`
   };
   let connectionAttempt: ConnectionAttempt | null = null;
 
@@ -600,6 +605,52 @@ export default function (pi: ExtensionAPI) {
     return Array.from(allTerminalNames()).sort();
   }
 
+  /**
+   * Hub: the `GET /status` snapshot. Pure reads — it mutates nothing and sends
+   * nothing, so observing the link cannot disturb it.
+   *
+   * Hub entry first, then clients sorted by name, so pollers see a stable order.
+   * `status`/`sinceSeconds` and `cwd` are omitted rather than invented when the
+   * hub has not heard them yet: a client is in `hubClients` from `register`, but
+   * its first `status_update` arrives a round trip later, and reporting a fresh
+   * peer as "idle" would be exactly the false inventory this endpoint exists to
+   * remove.
+   */
+  function buildStatusPayload() {
+    const now = Date.now();
+
+    const describe = (name: string, entryRole: "hub" | "client") => {
+      const status = getStatusFor(name);
+      const cwd = getCwdFor(name);
+      const context = getContextFor(name);
+      return {
+        name,
+        role: entryRole,
+        ...(status
+          ? {
+              status: statusIdentity(status),
+              sinceSeconds: Math.round((now - status.since) / 1000),
+            }
+          : {}),
+        ...(cwd ? { cwd } : {}),
+        context: context
+          ? { tokens: context.tokens, window: context.contextWindow }
+          : null,
+      };
+    };
+
+    return {
+      hub: terminalName,
+      port: DEFAULT_PORT,
+      terminals: [
+        describe(terminalName, "hub"),
+        ...Array.from(hubClients.values())
+          .sort()
+          .map((name) => describe(name, "client")),
+      ],
+    };
+  }
+
   function safeParse(data: string): LinkMessage | null {
     try {
       return JSON.parse(data);
@@ -975,10 +1026,22 @@ export default function (pi: ExtensionAPI) {
 
   function startHub(attempt: ConnectionAttempt): Promise<boolean> {
     return new Promise((resolve) => {
-      const server = new WebSocketServer({
-        port: DEFAULT_PORT,
-        host: "127.0.0.1",
+      // Owning the HTTP server is what makes `GET /status` possible: a port-bound
+      // `WebSocketServer` builds its own and answers every plain request with 426.
+      // `ws` forwards this server's `listening` and `error`, so the election below
+      // is unchanged.
+      const httpServer = createServer((req, res) => {
+        if (req.method === "GET" && req.url === "/status") {
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(JSON.stringify(buildStatusPayload()));
+          return;
+        }
+        res.writeHead(404);
+        res.end();
       });
+      attempt.httpServer = httpServer;
+
+      const server = new WebSocketServer({ server: httpServer });
       attempt.server = server;
 
       // The phase settles once. `error` and a pre-listen `close` both report the
@@ -988,16 +1051,19 @@ export default function (pi: ExtensionAPI) {
         if (settled) return;
         settled = true;
         if (attempt.server === server) attempt.server = null;
+        if (attempt.httpServer === httpServer) attempt.httpServer = null;
         resolve(established);
       };
 
       server.on("listening", () => {
         if (!attemptIsCurrent(attempt)) {
           server.close();
+          httpServer.close();
           settle(false);
           return;
         }
         wss = server;
+        hubHttpServer = httpServer;
         // If a client `/link-name` was in flight when the previous hub vanished,
         // this terminal is now establishing hub identity, so honor that pending
         // request. Otherwise keep the last hub-assigned identity — don't replay
@@ -1033,6 +1099,9 @@ export default function (pi: ExtensionAPI) {
         // Reached when a pending server is cancelled; a no-op once established.
         settle(false);
       });
+
+      // Last, so no forwarded event can arrive before its handler exists.
+      httpServer.listen(DEFAULT_PORT, "127.0.0.1");
     });
   }
 
@@ -1128,6 +1197,7 @@ export default function (pi: ExtensionAPI) {
       promise: Promise.resolve(),
       socket: null,
       server: null,
+      httpServer: null,
     };
     connectionAttempt = attempt;
     attempt.promise = runAttempt(attempt);
@@ -1172,8 +1242,13 @@ export default function (pi: ExtensionAPI) {
     const attempt = connectionAttempt;
     if (!attempt) return;
     connectionAttempt = null;
-    attempt.socket?.close();
-    attempt.server?.close();
+    // Read every handle first: closing the WS server can settle the attempt, and
+    // settling clears these fields. Closing the HTTP server is not optional — it
+    // holds the port, so a skipped close squats :9900 for the whole machine.
+    const { socket, server, httpServer } = attempt;
+    socket?.close();
+    server?.close();
+    httpServer?.close();
   }
 
   function scheduleReconnect() {
@@ -1219,6 +1294,8 @@ export default function (pi: ExtensionAPI) {
       hubClients.clear();
       wss.close();
       wss = null;
+      hubHttpServer?.close();
+      hubHttpServer = null;
     }
 
     role = "disconnected";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-link",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "WebSocket-based inter-terminal communication for Pi. Connect multiple Pi terminals over a local link network.",
   "author": "alvivar",
   "license": "MIT",