@commonlyai/cli 0.1.216 → 0.1.217

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.216",
+  "version": "0.1.217",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/daemon.js

@@ -38,6 +38,12 @@ import {
 } from '../lib/daemon-service.js';
 import { daemonLogsDir, daemonSeatLogPath, readLogTail } from '../lib/daemon-logs.js';
 import { loadDaemonState, saveDaemonState } from '../lib/daemon-state.js';
+import {
+  CLEAR_SCREEN, renderDaemonWatch, shouldRedraw, WATCH_INTERVAL_MS,
+} from '../lib/daemon-watch.js';
+import {
+  createReachCache, loadPodReach, readSessionLastTurn,
+} from '../lib/daemon-agent-states.js';
 import { installedCliVersion, startUpdateNotice, UPDATE_CHECK_OPT_OUT_ENV } from '../lib/update-check.js';
 
 // One supervised seat, as `commonly daemon status --verbose` names it. Two of these
@@ -58,6 +64,90 @@ export const formatSeatLine = (seat = {}) => {
   return `  ${seat.agentName}: ${seat.state} instance=${seat.instanceId || '-'} adapter=${seat.adapter || 'unknown'} model=${model}${effort} pid=${seat.pid || '-'} restarts=${restarts} lastTurn=${seat.lastTurnAt || 'never'}${error}`;
 };
 
+// `daemon status --watch`: one frame, then a redraw every 2 s on a terminal. Off a
+// terminal, or with NO_COLOR set, it prints one frame and returns. A failed
+// fetch is shown in the frame, so the loop keeps running through a brief outage.
+const watchDaemonStatus = async () => {
+  const redraw = shouldRedraw({ isTTY: process.stdout.isTTY });
+  // Each agent's pod comes from its token record. The verdict for a pod is read
+  // through the operator's login and cached for 10 s, so the 2 s frame does not
+  // re-read it. A failed read is thrown, so the next frame retries.
+  const reachFor = createReachCache({
+    load: (podId) => loadPodReach({
+      client: createClient({ instance: requireDaemonRecord().instanceUrl }),
+      podId,
+    }),
+  });
+  const frame = async () => {
+    try {
+      const record = requireDaemonRecord();
+      // A failed machine read still shows the local seats and logs, with the
+      // machine marked unreachable, so the operator can see what is running here.
+      let machine;
+      let machineNote = '';
+      try {
+        machine = await getDaemonMachineStatus({
+          client: createClient({ instance: record.instanceUrl, token: record.daemonToken }),
+          record,
+        });
+      } catch (error) {
+        machine = { name: record.machineName, status: 'unreachable', lastSeenAt: null };
+        machineNote = `Machine status unavailable (${error.message}): showing local seats only.`;
+      }
+      const seats = (loadDaemonState()?.seats || []).map((seat) => ({
+        ...seat,
+        // The supervisor stamps spawn time; the session store holds real turns.
+        lastTurnAt: readSessionLastTurn(seat.agentName),
+      }));
+      const logTails = {};
+      for (const seat of seats) {
+        const tail = readLogTail(daemonSeatLogPath(seat.agentName), 3);
+        logTails[seat.agentName] = tail ? tail.split('\n') : [];
+      }
+      let states = null;
+      let stateNote = '';
+      if (!getToken(record.instanceUrl)) {
+        stateNote = `Not logged in: showing local process state only. Run: commonly login --instance ${record.instanceUrl}`;
+      } else {
+        const podIds = [...new Set(seats.map((seat) => loadAgentToken(seat.agentName)?.podId).filter(Boolean))];
+        try {
+          states = await reachFor(podIds);
+        } catch (error) {
+          stateNote = `Agent states unavailable (${error.message}): showing local process state only`;
+        }
+      }
+      return renderDaemonWatch({
+        machine, seats, logTails, states, stateNote: [machineNote, stateNote].filter(Boolean).join(' '), now: Date.now(), width: process.stdout.columns || 80, color: redraw,
+      });
+    } catch (error) {
+      return daemonStatusErrorMessage(error);
+    }
+  };
+  if (!redraw) {
+    console.log(await frame());
+    return;
+  }
+  let busy = false;
+  const tick = async () => {
+    if (busy) return;
+    busy = true;
+    try {
+      process.stdout.write(`${CLEAR_SCREEN}${await frame()}\n`);
+    } finally {
+      busy = false;
+    }
+  };
+  await tick();
+  const timer = setInterval(tick, WATCH_INTERVAL_MS);
+  const stop = () => {
+    clearInterval(timer);
+    process.stdout.write('\n');
+    process.exit(0);
+  };
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+};
+
 const requireDaemonRecord = () => {
   const record = loadDaemonRecord();
   if (!record) {
@@ -571,7 +661,12 @@ Examples:
     .command('status')
     .description('Show the server-derived liveness of this machine')
     .option('--verbose', 'Include locally supervised seat state and process details')
+    .option('--watch', 'Redraw the machine and agent view every 2 s until Ctrl-C')
     .action(async (opts) => {
+      if (opts.watch) {
+        await watchDaemonStatus();
+        return;
+      }
       try {
         const record = requireDaemonRecord();
         const machine = await getDaemonMachineStatus({

package/src/lib/daemon-agent-states.js

@@ -0,0 +1,95 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// The server's verdict for each agent, as `daemon status --watch` shows it. The
+// verdict is deriveAgentState's (backend/services/agentStateService.ts), the
+// same one the Your Team row and the TASK-655 never-connected line use, so the
+// watch and the product name an agent's state the same way. It is read through
+// the operator's login, because the daemon's own credential cannot call the
+// per-pod agent-states route. Each agent's pod comes from its token record.
+
+// The reach states mapped to the words the watch prints. `reachable` is a
+// native or push-webhook agent the server always treats as up.
+const LABEL = {
+  listening: 'running',
+  reachable: 'running',
+  'gone-dark': 'stalled',
+  'never-connected': 'not connected',
+};
+
+// When one agent is installed in several pods, the most alive verdict wins.
+const RANK = ['running', 'stalled', 'not connected', 'unknown'];
+
+export const reachLabel = (reach) => LABEL[reach] || 'unknown';
+
+export const seatKey = (agentName, instanceId) => (
+  `${String(agentName || '').toLowerCase()}:${String(instanceId || 'default').toLowerCase()}`
+);
+
+const moreAlive = (a, b) => (RANK.indexOf(a) <= RANK.indexOf(b) ? a : b);
+
+// Reads one pod's agents and returns Map<seatKey, label>. `client` is a
+// user-token client.
+export const loadPodReach = async ({ client, podId }) => {
+  const body = await client.get(`/api/pods/${podId}/agent-states`);
+  const byAgent = new Map();
+  for (const agent of body?.agents || []) {
+    byAgent.set(seatKey(agent.agentName, agent.instanceId), reachLabel(agent.state));
+  }
+  return byAgent;
+};
+
+// The server allows 60 agent-states reads a minute per IP. Each pod is refreshed
+// once per TTL, and the TTL stretches with the pod count, so N pods cost about 50
+// reads a minute whatever N is: 1.2 s per pod at least, and never below `ttlMs`.
+const PER_POD_SPACING_MS = 1_200;
+
+// Caches each pod's verdict, so the 2 s watch frame does not re-read every pod.
+// A failed refresh keeps the pod's last verdict and waits one TTL before trying
+// again, so a 429 is neither discarded nor retried every frame. A pod with no
+// earlier verdict throws, and the next call retries it. `load(podId)` returns
+// Map<seatKey, label>. Returns `reachFor(podIds)`, which merges the pods' maps.
+export const createReachCache = ({ load, ttlMs = 10_000, now = Date.now }) => {
+  const cached = new Map();
+  const reachFor = async (podIds) => {
+    const ttl = Math.max(ttlMs, podIds.length * PER_POD_SPACING_MS);
+    const merged = new Map();
+    for (const podId of podIds) {
+      const hit = cached.get(podId);
+      let agents;
+      if (hit && now() - hit.loadedAt < ttl) {
+        agents = hit.agents;
+      } else {
+        try {
+          agents = await load(podId);
+        } catch (error) {
+          if (!hit) throw error;
+          agents = hit.agents;
+        }
+        cached.set(podId, { agents, loadedAt: now() });
+      }
+      for (const [key, label] of agents) {
+        merged.set(key, merged.has(key) ? moreAlive(merged.get(key), label) : label);
+      }
+    }
+    return merged;
+  };
+  return reachFor;
+};
+
+// The agent's last supervised turn, from its session store, the record
+// `agent list` reads. The most recent entry across pods, or null. The
+// supervisor's own stamp is the spawn time, so the watch does not use it.
+export const readSessionLastTurn = (name, { home = homedir() } = {}) => {
+  try {
+    const sessions = JSON.parse(readFileSync(join(home, '.commonly', 'sessions', `${name}.json`), 'utf8'));
+    let latest = null;
+    for (const entry of Object.values(sessions || {})) {
+      if (entry?.lastTurn && (!latest || entry.lastTurn > latest)) latest = entry.lastTurn;
+    }
+    return latest;
+  } catch {
+    return null;
+  }
+};

package/src/lib/daemon-watch.js

@@ -0,0 +1,115 @@
+// The live view behind `commonly daemon status --watch`: the machine, then one
+// block per supervised agent with its state, last turn, last error and the tail
+// of its log. Rendering is a pure function of its inputs so the layout can be
+// tested at fixed widths; the redraw loop lives in the command.
+
+import { seatKey } from './daemon-agent-states.js';
+
+export const WATCH_INTERVAL_MS = 2000;
+
+const ANSI = {
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+  reset: '\x1b[0m',
+};
+
+// A redraw clears the screen and returns the cursor home. Plain ANSI, no
+// dependency; the caller decides whether to use it at all.
+export const CLEAR_SCREEN = '\x1b[H\x1b[2J';
+
+// The view is for a person watching a terminal. Anything else gets one print.
+export const shouldRedraw = ({ isTTY, env = process.env } = {}) => (
+  Boolean(isTTY) && !(env && env.NO_COLOR !== undefined && env.NO_COLOR !== '')
+);
+
+const relative = (iso, now) => {
+  if (!iso) return 'never';
+  const ms = now - new Date(iso).getTime();
+  if (!Number.isFinite(ms)) return 'unknown';
+  if (ms < 60_000) return `${Math.max(0, Math.round(ms / 1000))}s ago`;
+  if (ms < 3_600_000) return `${Math.round(ms / 60_000)}m ago`;
+  return `${Math.round(ms / 3_600_000)}h ago`;
+};
+
+// Terminal control sequences in a log or state field would reach the operator's
+// terminal: a line could clear the watch, set the title, or write the clipboard.
+// Strip OSC and CSI sequences, bare escapes, and C0/C1 controls before anything
+// else. Tabs become spaces so the column count stays honest.
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const OSC = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g;
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const CSI = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const ESC = /\x1b[@-Z\\-_]/g;
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const CONTROL = /[\x00-\x08\x0a-\x1f\x7f-\x9f]/g;
+export const stripControls = (text) => String(text ?? '')
+  .replace(OSC, '').replace(CSI, '').replace(ESC, '').replace(CONTROL, '').replace(/\t/g, '  ');
+
+// Credential shapes the CLI knows, plus the forms that carry a credential in a
+// log without a known prefix: `Authorization: Basic …`, and a quoted or bare
+// `token`/`password`/`secret`/`api_key` field. Generic key/value redaction can
+// over-match, which is the cheaper error for a watch that prints logs.
+const CREDENTIAL = [
+  [/cm_(?:daemon|agent|user)_[A-Za-z0-9_-]+/g, '[redacted]'],
+  [/\bBearer\s+\S+/gi, '[redacted]'],
+  [/\bBasic\s+[A-Za-z0-9+/=._-]+/g, '[redacted]'],
+  [/(\bauthorization\s*[:=]\s*)(?:(?:basic|bearer|digest|token)\s+)?\S+/gi, '$1[redacted]'],
+  [/(["']?\b(?:token|password|passwd|secret|api[_-]?key|access[_-]?token|refresh[_-]?token)\b["']?\s*[:=]\s*)(["']?)[^\s"',}&]+\2/gi, '$1$2[redacted]$2'],
+];
+const redact = (text) => CREDENTIAL.reduce((value, [shape, replacement]) => value.replace(shape, replacement), text);
+
+// Every field the watch prints goes through here: control sequences out,
+// credentials redacted, then clipped to the width.
+const clip = (text, width) => {
+  const value = redact(stripControls(text));
+  return value.length <= width ? value : `${value.slice(0, Math.max(0, width - 1))}…`;
+};
+
+// A log line can carry a credential or a whole prompt; the same boundary covers it.
+export const safeLogLine = (line, width) => clip(line, width);
+
+// The state is the server's verdict, read by daemon-agent-states. `states` is
+// that Map. Without it (no login, or the read failed) the seat shows its local
+// process state, labelled `local`, and never a server word. An agent the verdict
+// does not list has no installation on its pod.
+export const agentStateLabel = (seat = {}, states = null) => {
+  if (!states) return `local ${seat.state || 'unknown'}`;
+  return states.get(seatKey(seat.agentName, seat.instanceId)) || 'not registered';
+};
+
+const agentBlock = (seat, { now, width, color, logTail, states }) => {
+  const dim = (text) => (color ? `${ANSI.dim}${text}${ANSI.reset}` : text);
+  const bold = (text) => (color ? `${ANSI.bold}${text}${ANSI.reset}` : text);
+  const lines = [
+    `${bold(clip(seat.agentName || 'unknown', width))}  ${agentStateLabel(seat, states)}  last turn ${relative(seat.lastTurnAt, now)}`,
+  ];
+  if (seat.lastError) lines.push(clip(`  error: ${seat.lastError}`, width));
+  for (const line of logTail || []) lines.push(dim(`  ${safeLogLine(line, Math.max(10, width - 2))}`));
+  return lines;
+};
+
+// Inputs: `machine` { name, status, lastSeenAt }, `seats` (from the daemon state
+// file), `logTails` { [agentName]: string[] }, `states` (Map from
+// loadReachByAgent, or null), `stateNote` (why states is null), `now` (ms),
+// `width` (columns).
+export const renderDaemonWatch = ({
+  machine = {}, seats = [], logTails = {}, states = null, stateNote = '', now = Date.now(), width = 80, color = false,
+} = {}) => {
+  const bold = (text) => (color ? `${ANSI.bold}${text}${ANSI.reset}` : text);
+  const out = [
+    bold(clip(`${machine.name || 'machine'}: ${machine.status || 'unknown'}`, width)),
+    clip(`last heartbeat ${relative(machine.lastSeenAt, now)}`, width),
+  ];
+  if (stateNote) out.push(clip(stateNote, width));
+  out.push('');
+  if (!seats.length) {
+    out.push('No supervised agents on this machine.');
+    return out.join('\n');
+  }
+  for (const seat of seats) {
+    out.push(...agentBlock(seat, { now, width, color, logTail: logTails[seat.agentName] || [], states }));
+    out.push('');
+  }
+  return out.join('\n').replace(/\n+$/, '');
+};