sentinelayer-cli 0.8.5 → 0.8.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/session.js

@@ -49,8 +49,10 @@ import {
   recordSessionProvisionedIdentities,
 } from "../session/store.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
+import { readSessionPreview } from "../session/preview.js";
 import { syncSessionMetadataToApi } from "../session/sync.js";
 import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
+import { mergeLiveSources } from "../session/live-source.js";
 import {
   buildDashboardUrl,
   buildTemplateLaunchPlan,
@@ -452,7 +454,11 @@ export function registerSessionCommand(program) {
     .command("read <sessionId>")
     .description("Read recent session messages")
     .option("--tail <n>", "Number of recent events", "20")
-    .option("--follow", "Continuously follow new events")
+    .option("--follow", "Continuously follow new events (local fs poll)")
+    .option(
+      "--live",
+      "Subscribe to SSE + fs.watch combined source (replaces --follow). Same-machine peers via fs.watch, remote peers via SSE; events deduped by id.",
+    )
     .option(
       "--remote",
       "Hydrate from the SentinelLayer API before reading (pulls web-posted messages into the local NDJSON)",
@@ -515,6 +521,49 @@ export function registerSessionCommand(program) {
         return;
       }
 
+      if (options.live) {
+        if (!emitJson) {
+          console.log(
+            pc.gray(
+              `Live-tailing ${normalizedSessionId} (SSE + fs.watch)… Ctrl+C to stop.`,
+            ),
+          );
+        }
+        const ac = new AbortController();
+        const onSigint = () => ac.abort();
+        process.on("SIGINT", onSigint);
+        const session = await resolveActiveAuthSession({
+          cwd: targetPath,
+          env: process.env,
+          autoRotate: false,
+        }).catch(() => null);
+        const apiBaseUrl = session?.apiUrl || "";
+        const token = session?.token || "";
+        try {
+          for await (const item of mergeLiveSources({
+            sessionId: normalizedSessionId,
+            targetPath,
+            apiBaseUrl: apiBaseUrl || undefined,
+            token: token || undefined,
+            signal: ac.signal,
+          })) {
+            if (item.event) {
+              if (emitJson) {
+                console.log(JSON.stringify({ source: item.source, event: item.event }));
+              } else {
+                const sourceTag = item.source === "sse" ? pc.cyan("[sse]") : pc.gray("[fs] ");
+                console.log(`${sourceTag} ${formatEventLine(item.event)}`);
+              }
+            } else if (item.error && !emitJson) {
+              console.log(pc.yellow(`(${item.source} stream: ${item.error})`));
+            }
+          }
+        } finally {
+          process.removeListener("SIGINT", onSigint);
+        }
+        return;
+      }
+
       if (!emitJson) {
         console.log(pc.gray(`Following session ${normalizedSessionId}... Press Ctrl+C to stop.`));
       }
@@ -847,35 +896,65 @@ export function registerSessionCommand(program) {
 
   session
     .command("history")
-    .description("Past conversations — alias for `session list --include-archived`")
+    .description(
+      "Past conversations with a one-line preview of the most recent message (alias for `session list --include-archived` + previews)",
+    )
     .option("--limit <n>", "Maximum sessions to return", "50")
+    .option("--no-preview", "Skip the per-session preview lookup")
     .option("--path <path>", "Workspace path for sessions", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
       const limit = parsePositiveInteger(options.limit, "limit", 50);
+      const wantPreview = options.preview !== false;
       const sessions = await listAllSessions({ targetPath });
       const trimmed = shouldEmitJson(options, command) ? sessions : sessions.slice(0, limit);
-      const payload = {
-        command: "session history",
-        targetPath,
-        count: sessions.length,
-        sessions: trimmed,
-      };
+
+      let previews = new Map();
+      if (wantPreview && trimmed.length > 0) {
+        const entries = await Promise.all(
+          trimmed.map(async (item) => [
+            item.sessionId,
+            await readSessionPreview(item.sessionId, { targetPath }),
+          ]),
+        );
+        previews = new Map(entries);
+      }
+
       if (shouldEmitJson(options, command)) {
+        const payload = {
+          command: "session history",
+          targetPath,
+          count: sessions.length,
+          sessions: trimmed.map((item) => ({
+            ...item,
+            preview: previews.get(item.sessionId) || null,
+          })),
+        };
         console.log(JSON.stringify(payload, null, 2));
         return;
       }
+
       if (sessions.length === 0) {
         console.log(pc.yellow("No sessions in cache."));
         return;
       }
       for (const item of trimmed) {
-        console.log(
-          `${item.archiveStatus.padEnd(8)} ${item.sessionId} created=${item.createdAt}${
-            item.archivedAt ? ` archived=${item.archivedAt}` : ""
-          }`,
-        );
+        const archive = item.archiveStatus.padEnd(8);
+        const head =
+          `${archive} ${item.sessionId} created=${item.createdAt}` +
+          (item.archivedAt ? ` archived=${item.archivedAt}` : "");
+        if (!wantPreview) {
+          console.log(head);
+          continue;
+        }
+        const preview = previews.get(item.sessionId);
+        if (preview && preview.message) {
+          const speaker = preview.agentId ? `${preview.agentId}: ` : "";
+          console.log(`${head}\n  ${pc.gray(`${speaker}${preview.message}`)}`);
+        } else {
+          console.log(`${head}\n  ${pc.gray("(no messages yet)")}`);
+        }
       }
       if (sessions.length > trimmed.length) {
         console.log(

package/src/session/live-source.js

@@ -0,0 +1,308 @@
+/**
+ * Live session-event source — composes `fs.watch` (instant local notify
+ * when the NDJSON file changes) and SSE (`/api/v1/sessions/<id>/stream`,
+ * server-pushed updates) into a single async iterator.
+ *
+ * The two lanes give us the WebRTC-like behavior the user asked about
+ * without the WebRTC operational tax: same-machine peers see each
+ * other's writes through `fs.watch` immediately; remote peers receive
+ * via SSE the moment the API persists. A single stream emits both, with
+ * dedup by event id so the same event seen on both lanes only surfaces
+ * once.
+ *
+ * Tests inject `_watch`, `_sse`, and `_readEvents` so the iterator can
+ * be exercised hermetically; production uses `node:fs` watch + native
+ * fetch streaming.
+ */
+
+import fs from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import { resolveSessionPaths } from "./paths.js";
+import { readStream } from "./stream.js";
+
+const DEFAULT_RECONNECT_BACKOFF_MS = 2_000;
+const MAX_RECONNECT_BACKOFF_MS = 30_000;
+
+function eventKey(event) {
+  if (!event || typeof event !== "object") return null;
+  if (event.id) return `id:${event.id}`;
+  if (event.eventId) return `id:${event.eventId}`;
+  const ts = event.ts || event.timestamp;
+  const kind = event.event || event.type;
+  if (ts && kind) return `${ts}::${kind}`;
+  return null;
+}
+
+/**
+ * Watch a session's NDJSON file with `fs.watch`. Whenever the file
+ * changes (append-only writes happen on every event), re-read the tail
+ * and emit any events the consumer hasn't seen yet. Falls back to a
+ * 500 ms poll on platforms where `fs.watch` is unreliable (some
+ * Windows + network mounts) — controlled by `_watch` for tests.
+ *
+ * Async generator yields `{ source: "fs", event }`.
+ */
+export async function* watchLocalStream({
+  sessionId,
+  targetPath,
+  signal,
+  initialTail = 50,
+  _watch = fs.watch,
+  _readEvents = readStream,
+} = {}) {
+  if (!sessionId) return;
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  let lastTs = null;
+
+  // Replay the tail first so any caller getting the iterator catches
+  // up with the in-flight context before live events start arriving.
+  const initial = await _readEvents(sessionId, { targetPath, tail: initialTail });
+  for (const event of initial) {
+    const candidate = event.ts || event.timestamp;
+    if (candidate) lastTs = candidate;
+    yield { source: "fs", event };
+  }
+
+  let pendingResolve = null;
+  let pendingPromise = null;
+  const queue = [];
+
+  function notify() {
+    if (pendingResolve) {
+      const r = pendingResolve;
+      pendingResolve = null;
+      pendingPromise = null;
+      r();
+    }
+  }
+
+  let watcher = null;
+  try {
+    watcher = _watch(paths.streamPath, { persistent: false }, () => notify());
+  } catch {
+    // If watch can't attach (file missing yet, locked filesystem), we
+    // fall back to a 500ms poll so the iterator still makes progress.
+    watcher = {
+      close() {},
+    };
+    (async () => {
+      while (!signal?.aborted) {
+        await sleep(500);
+        notify();
+      }
+    })();
+  }
+
+  const aborted = () => Boolean(signal?.aborted);
+  if (signal) signal.addEventListener("abort", () => notify(), { once: true });
+
+  try {
+    while (!aborted()) {
+      // Wait for any change notification.
+      pendingPromise = new Promise((resolve) => {
+        pendingResolve = resolve;
+      });
+      await pendingPromise;
+      if (aborted()) break;
+
+      const events = await _readEvents(sessionId, { targetPath, tail: 0, since: lastTs });
+      for (const event of events) {
+        const candidate = event.ts || event.timestamp;
+        if (lastTs && candidate && candidate <= lastTs) continue;
+        if (candidate) lastTs = candidate;
+        queue.push({ source: "fs", event });
+      }
+      while (queue.length > 0) {
+        yield queue.shift();
+      }
+    }
+  } finally {
+    try {
+      watcher.close();
+    } catch {
+      /* swallow */
+    }
+  }
+}
+
+/**
+ * Subscribe to the API's SSE stream for a session. Emits each parsed
+ * data: line as `{ source: "sse", event }`. Auto-reconnects on
+ * connection drop with exponential backoff capped at 30s.
+ *
+ * `_sseFetch` defaults to `fetch` but tests can stub it.
+ */
+export async function* watchRemoteStream({
+  apiBaseUrl,
+  sessionId,
+  token,
+  signal,
+  _sseFetch = fetch,
+  reconnectBackoffMs = DEFAULT_RECONNECT_BACKOFF_MS,
+} = {}) {
+  if (!apiBaseUrl || !sessionId || !token) return;
+  const endpoint = `${apiBaseUrl.replace(/\/+$/, "")}/api/v1/sessions/${encodeURIComponent(
+    sessionId,
+  )}/stream`;
+  let backoff = reconnectBackoffMs;
+
+  while (!signal?.aborted) {
+    let response;
+    try {
+      response = await _sseFetch(endpoint, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: "text/event-stream",
+        },
+        signal,
+      });
+    } catch (err) {
+      if (signal?.aborted) return;
+      yield { source: "sse", error: String(err?.message || err) };
+      await sleep(backoff);
+      backoff = Math.min(backoff * 2, MAX_RECONNECT_BACKOFF_MS);
+      continue;
+    }
+
+    if (!response || !response.ok || !response.body) {
+      yield { source: "sse", error: `HTTP ${response?.status || "?"}` };
+      await sleep(backoff);
+      backoff = Math.min(backoff * 2, MAX_RECONNECT_BACKOFF_MS);
+      continue;
+    }
+
+    backoff = reconnectBackoffMs;
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    try {
+      while (!signal?.aborted) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const frames = buffer.split(/\n\n/);
+        buffer = frames.pop() || "";
+        for (const frame of frames) {
+          for (const line of frame.split(/\r?\n/)) {
+            if (!line.startsWith("data:")) continue;
+            const payload = line.slice(5).trim();
+            if (!payload || payload === "[done]") continue;
+            try {
+              const event = JSON.parse(payload);
+              yield { source: "sse", event };
+            } catch {
+              yield { source: "sse", raw: payload };
+            }
+          }
+        }
+      }
+    } finally {
+      try {
+        await reader.cancel();
+      } catch {
+        /* swallow */
+      }
+    }
+
+    if (signal?.aborted) return;
+    await sleep(backoff);
+  }
+}
+
+/**
+ * Compose `fs.watch` and SSE into one event stream. Each emitted event
+ * carries its `source` so consumers can tell which lane saw it first;
+ * we dedup by event id so the same event arriving on both lanes only
+ * surfaces once.
+ *
+ * @param {object} params
+ * @param {string} params.sessionId
+ * @param {string} [params.targetPath]
+ * @param {string} [params.apiBaseUrl]
+ * @param {string} [params.token]
+ * @param {AbortSignal} [params.signal]
+ * @returns {AsyncIterable<{source: "fs"|"sse", event?: object, raw?: string, error?: string}>}
+ */
+export async function* mergeLiveSources({
+  sessionId,
+  targetPath,
+  apiBaseUrl,
+  token,
+  signal,
+  _localIterator,
+  _remoteIterator,
+} = {}) {
+  if (!sessionId) return;
+
+  const localIterable = _localIterator
+    ? _localIterator
+    : watchLocalStream({ sessionId, targetPath, signal });
+  const remoteIterable =
+    _remoteIterator || (apiBaseUrl && token)
+      ? _remoteIterator
+        ? _remoteIterator
+        : watchRemoteStream({ apiBaseUrl, sessionId, token, signal })
+      : null;
+
+  const seen = new Set();
+  const queue = [];
+  let pending = null;
+
+  const wakeUp = () => {
+    if (pending) {
+      const r = pending;
+      pending = null;
+      r();
+    }
+  };
+
+  async function pump(iterable) {
+    if (!iterable) return;
+    try {
+      for await (const item of iterable) {
+        queue.push(item);
+        wakeUp();
+        if (signal?.aborted) break;
+      }
+    } catch (err) {
+      queue.push({ source: "merge", error: String(err?.message || err) });
+      wakeUp();
+    }
+  }
+
+  pump(localIterable);
+  if (remoteIterable) pump(remoteIterable);
+
+  // Make sure abort wakes the iterator promptly so the consumer doesn't
+  // hang waiting on a `pending` promise that nothing is going to
+  // resolve once the upstream sources finish.
+  if (signal) signal.addEventListener("abort", () => wakeUp(), { once: true });
+
+  while (!signal?.aborted) {
+    if (queue.length === 0) {
+      await new Promise((resolve) => {
+        pending = resolve;
+      });
+      if (signal?.aborted) break;
+      continue;
+    }
+    const item = queue.shift();
+    if (item.event) {
+      const key = eventKey(item.event);
+      if (key) {
+        if (seen.has(key)) continue;
+        seen.add(key);
+        if (seen.size > 5000) {
+          // bound memory — older keys roll out
+          const trimmed = Array.from(seen).slice(-2500);
+          seen.clear();
+          for (const k of trimmed) seen.add(k);
+        }
+      }
+    }
+    yield item;
+  }
+}

package/src/session/preview.js

@@ -0,0 +1,91 @@
+/**
+ * Per-session message preview — used by `slc session history` to show
+ * the last meaningful line of each past conversation, ChatGPT-style.
+ *
+ * "Meaningful" filters out heartbeats / agent_join / file-lock churn
+ * so the preview doesn't get drowned in machine traffic.
+ */
+
+import { readStream } from "./stream.js";
+
+const PREVIEW_EVENTS = new Set([
+  "session_message",
+  "session_say",
+  "agent_response",
+  "human_relay",
+  "daemon_alert",
+  "session_admin_kill",
+]);
+
+const HEAD_LIMIT = 40;
+const PREVIEW_TAIL_SCAN = 50;
+
+function trim(value, limit = HEAD_LIMIT) {
+  const text = String(value == null ? "" : value).trim();
+  if (!text) return "";
+  if (text.length <= limit) return text;
+  return `${text.slice(0, Math.max(0, limit - 1))}…`;
+}
+
+/**
+ * Pick the most recent user-visible message from an event list. Returns
+ * the head of its body and the speaker so the caller can render
+ * `<agentId>: <message>`.
+ *
+ * @param {Array<object>} events
+ * @returns {{ts: string|null, agentId: string|null, kind: string|null, message: string|null}}
+ */
+export function pickLatestPreview(events = []) {
+  if (!Array.isArray(events) || events.length === 0) {
+    return { ts: null, agentId: null, kind: null, message: null };
+  }
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const event = events[i] || {};
+    const kind = String(event.event || event.type || "").trim();
+    if (!kind || !PREVIEW_EVENTS.has(kind)) continue;
+    const payload = event.payload && typeof event.payload === "object" ? event.payload : {};
+    const text =
+      payload.message ||
+      payload.response ||
+      payload.alert ||
+      payload.reason ||
+      payload.text;
+    if (!text) continue;
+    return {
+      ts: event.ts || event.timestamp || null,
+      agentId:
+        (event.agent && event.agent.id) ||
+        event.agentId ||
+        payload.agentId ||
+        null,
+      kind,
+      message: trim(text),
+    };
+  }
+  return { ts: null, agentId: null, kind: null, message: null };
+}
+
+/**
+ * Lift a preview line for a single session by tailing the stream.
+ * Failures are non-fatal — missing stream / parse errors yield a null
+ * preview rather than throwing, so the history listing stays resilient
+ * across mixed-state caches.
+ *
+ * @param {string} sessionId
+ * @param {{targetPath?: string, tail?: number}} [options]
+ * @returns {Promise<{ts: string|null, agentId: string|null, kind: string|null, message: string|null}>}
+ */
+export async function readSessionPreview(
+  sessionId,
+  { targetPath = process.cwd(), tail = PREVIEW_TAIL_SCAN } = {},
+) {
+  if (!sessionId) {
+    return { ts: null, agentId: null, kind: null, message: null };
+  }
+  try {
+    const events = await readStream(sessionId, { targetPath, tail });
+    return pickLatestPreview(events);
+  } catch {
+    return { ts: null, agentId: null, kind: null, message: null };
+  }
+}