sentinelayer-cli 0.8.3 → 0.8.5

package/package.json

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

package/src/commands/session.js

@@ -1,3 +1,4 @@
+import fsp from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 import { randomUUID } from "node:crypto";
@@ -44,10 +45,12 @@ import {
   DEFAULT_TTL_SECONDS,
   getSession,
   listActiveSessions,
+  listAllSessions,
   recordSessionProvisionedIdentities,
 } from "../session/store.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
 import { syncSessionMetadataToApi } from "../session/sync.js";
+import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
 import {
   buildDashboardUrl,
   buildTemplateLaunchPlan,
@@ -450,6 +453,10 @@ export function registerSessionCommand(program) {
     .description("Read recent session messages")
     .option("--tail <n>", "Number of recent events", "20")
     .option("--follow", "Continuously follow new events")
+    .option(
+      "--remote",
+      "Hydrate from the SentinelLayer API before reading (pulls web-posted messages into the local NDJSON)",
+    )
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, options, command) => {
@@ -461,6 +468,29 @@ export function registerSessionCommand(program) {
       const tail = parsePositiveInteger(options.tail, "tail", 20);
       const emitJson = shouldEmitJson(options, command);
 
+      let hydration = null;
+      if (options.remote) {
+        hydration = await hydrateSessionFromRemote({
+          sessionId: normalizedSessionId,
+          targetPath,
+        });
+        if (!emitJson) {
+          if (hydration.ok) {
+            console.log(
+              pc.gray(
+                `Hydrated from remote: relayed=${hydration.relayed} dropped=${hydration.dropped}.`,
+              ),
+            );
+          } else {
+            console.log(
+              pc.yellow(
+                `Remote hydrate skipped (${hydration.reason}); showing local stream only.`,
+              ),
+            );
+          }
+        }
+      }
+
       if (!options.follow) {
         const events = await readStream(normalizedSessionId, {
           targetPath,
@@ -473,6 +503,7 @@ export function registerSessionCommand(program) {
           tail,
           count: events.length,
           events,
+          remote: hydration,
         };
         if (emitJson) {
           console.log(JSON.stringify(payload, null, 2));
@@ -499,6 +530,59 @@ export function registerSessionCommand(program) {
       }
     });
 
+  session
+    .command("sync <sessionId>")
+    .description(
+      "Pull human messages from the SentinelLayer API into the local NDJSON stream",
+    )
+    .option(
+      "--since <iso>",
+      "Override the persisted cursor and start from this ISO timestamp",
+    )
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const sinceArg = options.since == null ? undefined : String(options.since);
+
+      const result = await hydrateSessionFromRemote({
+        sessionId: normalizedSessionId,
+        targetPath,
+        since: sinceArg,
+      });
+
+      const payload = {
+        command: "session sync",
+        targetPath,
+        sessionId: normalizedSessionId,
+        ok: result.ok,
+        reason: result.reason || "",
+        relayed: result.relayed,
+        dropped: result.dropped,
+        cursor: result.cursor,
+        persistedCursor: result.persistedCursor,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      if (result.ok) {
+        console.log(
+          `Hydrated session ${normalizedSessionId}: relayed=${result.relayed} dropped=${result.dropped}.`,
+        );
+      } else {
+        console.log(
+          pc.yellow(
+            `Hydrate skipped (${result.reason}). Local stream is unchanged; cursor=${result.cursor || "<none>"}.`,
+          ),
+        );
+      }
+    });
+
   session
     .command("status <sessionId>")
     .description("Show session status, agents, and health")
@@ -581,6 +665,94 @@ export function registerSessionCommand(program) {
       }
     });
 
+  session
+    .command("export <sessionId>")
+    .description(
+      "Export full transcript + metadata + agents + tasks as JSON (compliance / portability / context handoff)",
+    )
+    .option(
+      "--format <fmt>",
+      "Output format: json (single object) or ndjson (one event per line)",
+      "json",
+    )
+    .option("--out <file>", "Write to file instead of stdout")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .action(async (sessionId, options) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const format = String(options.format || "json").trim().toLowerCase();
+      if (format !== "json" && format !== "ndjson") {
+        throw new Error(`--format must be 'json' or 'ndjson' (received '${format}').`);
+      }
+
+      const sessionPayload = await getSession(normalizedSessionId, { targetPath });
+      if (!sessionPayload) {
+        throw new Error(`Session '${normalizedSessionId}' was not found.`);
+      }
+
+      const [agents, events, tasks] = await Promise.all([
+        listAgents(normalizedSessionId, {
+          targetPath,
+          includeInactive: true,
+        }),
+        readStream(normalizedSessionId, {
+          targetPath,
+          tail: 0,
+        }),
+        listSessionTasks(normalizedSessionId, {
+          targetPath,
+          limit: 5_000,
+        }),
+      ]);
+
+      let output;
+      if (format === "ndjson") {
+        const lines = [];
+        lines.push(JSON.stringify({ kind: "session", value: sessionPayload }));
+        for (const agent of agents) lines.push(JSON.stringify({ kind: "agent", value: agent }));
+        for (const event of events) lines.push(JSON.stringify({ kind: "event", value: event }));
+        for (const task of tasks.tasks || []) lines.push(JSON.stringify({ kind: "task", value: task }));
+        output = `${lines.join("\n")}\n`;
+      } else {
+        output = `${JSON.stringify(
+          {
+            command: "session export",
+            exportedAt: new Date().toISOString(),
+            session: sessionPayload,
+            agents,
+            events,
+            tasks: tasks.tasks || [],
+            counts: {
+              agents: agents.length,
+              events: events.length,
+              tasks: (tasks.tasks || []).length,
+            },
+          },
+          null,
+          2,
+        )}\n`;
+      }
+
+      const outArg = normalizeString(options.out);
+      if (outArg) {
+        const outPath = path.resolve(process.cwd(), outArg);
+        await fsp.mkdir(path.dirname(outPath), { recursive: true });
+        await fsp.writeFile(outPath, output, "utf-8");
+        console.log(
+          pc.gray(
+            `Exported ${events.length} events / ${agents.length} agents / ${
+              (tasks.tasks || []).length
+            } tasks → ${outPath}`,
+          ),
+        );
+      } else {
+        process.stdout.write(output);
+      }
+    });
+
   session
     .command("leave <sessionId>")
     .description("Leave a session")
@@ -617,31 +789,99 @@ export function registerSessionCommand(program) {
 
   session
     .command("list")
-    .description("List active sessions")
+    .description("List sessions in the local workspace cache")
+    .option(
+      "--include-archived",
+      "Include archived/expired sessions (past conversations)",
+    )
+    .option(
+      "--limit <n>",
+      "Maximum sessions to return (default 50; ignored on --json)",
+      "50",
+    )
     .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 sessions = await listActiveSessions({
-        targetPath,
-      });
+      const includeArchived = Boolean(options.includeArchived);
+      const limit = parsePositiveInteger(options.limit, "limit", 50);
+      const sessions = includeArchived
+        ? await listAllSessions({ targetPath })
+        : await listActiveSessions({ targetPath });
+      const trimmed = shouldEmitJson(options, command) ? sessions : sessions.slice(0, limit);
       const payload = {
         command: "session list",
         targetPath,
+        includeArchived,
         count: sessions.length,
-        sessions,
+        sessions: trimmed,
       };
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
         return;
       }
       if (sessions.length === 0) {
-        console.log(pc.yellow("No active sessions."));
+        console.log(
+          pc.yellow(
+            includeArchived
+              ? "No sessions in cache."
+              : "No active sessions. Run with --include-archived to see history.",
+          ),
+        );
+        return;
+      }
+      for (const item of trimmed) {
+        const archive = item.archiveStatus ? ` archive=${item.archiveStatus}` : "";
+        console.log(
+          `${item.sessionId} status=${item.status}${archive} created=${item.createdAt} expires=${item.expiresAt}`,
+        );
+      }
+      if (sessions.length > trimmed.length) {
+        console.log(
+          pc.gray(
+            `… ${sessions.length - trimmed.length} more (raise --limit or use --json).`,
+          ),
+        );
+      }
+    });
+
+  session
+    .command("history")
+    .description("Past conversations — alias for `session list --include-archived`")
+    .option("--limit <n>", "Maximum sessions to return", "50")
+    .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 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,
+      };
+      if (shouldEmitJson(options, command)) {
+        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 sessions) {
+      for (const item of trimmed) {
+        console.log(
+          `${item.archiveStatus.padEnd(8)} ${item.sessionId} created=${item.createdAt}${
+            item.archivedAt ? ` archived=${item.archivedAt}` : ""
+          }`,
+        );
+      }
+      if (sessions.length > trimmed.length) {
         console.log(
-          `${item.sessionId} status=${item.status} created_at=${item.createdAt} expires_at=${item.expiresAt}`
+          pc.gray(
+            `… ${sessions.length - trimmed.length} more (raise --limit or use --json).`,
+          ),
         );
       }
     });

package/src/session/remote-hydrate.js

@@ -0,0 +1,95 @@
+/**
+ * One-shot remote hydrator for the local NDJSON stream.
+ *
+ * Wraps `pollHumanMessages` (which speaks to the SentinelLayer API) with
+ * a persisted cursor + `appendToStream`, so a CLI invocation can pull
+ * web-posted messages into the local session log on demand. The
+ * background daemon already does this on a poll loop; this module is
+ * the synchronous counterpart that powers `slc session sync` and
+ * `slc session read --remote`.
+ */
+
+import { pollHumanMessages } from "./sync.js";
+import { appendToStream } from "./stream.js";
+import { readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
+
+/**
+ * Fetch new human messages for a session, append them to the local
+ * stream, and advance the persisted cursor. Returns a structured
+ * summary the CLI can render directly. Failures degrade — we never
+ * throw out of this helper for transient/auth issues so wrappers can
+ * still serve a local-only read.
+ *
+ * @param {object} params
+ * @param {string} params.sessionId
+ * @param {string} [params.targetPath]
+ * @param {string|null} [params.since]   - Override persisted cursor.
+ * @param {Function}    [params._poll]   - Test seam.
+ * @param {Function}    [params._append] - Test seam.
+ * @returns {Promise<{ok: boolean, reason: string, relayed: number, dropped: number, cursor: string|null, persistedCursor: boolean}>}
+ */
+export async function hydrateSessionFromRemote({
+  sessionId,
+  targetPath = process.cwd(),
+  since = undefined,
+  _poll = pollHumanMessages,
+  _append = appendToStream,
+} = {}) {
+  if (!sessionId || typeof sessionId !== "string") {
+    return {
+      ok: false,
+      reason: "invalid_session_id",
+      relayed: 0,
+      dropped: 0,
+      cursor: null,
+      persistedCursor: false,
+    };
+  }
+
+  const startCursor =
+    typeof since === "string" || since === null
+      ? since
+      : await readSyncCursor(sessionId, { targetPath });
+
+  const polled = await _poll(sessionId, {
+    targetPath,
+    since: startCursor,
+  });
+
+  if (!polled || !polled.ok) {
+    return {
+      ok: false,
+      reason: polled?.reason || "poll_failed",
+      relayed: 0,
+      dropped: Array.isArray(polled?.dropped) ? polled.dropped.length : 0,
+      cursor: typeof polled?.cursor === "string" ? polled.cursor : startCursor || null,
+      persistedCursor: false,
+    };
+  }
+
+  let relayed = 0;
+  for (const event of polled.events || []) {
+    try {
+      await _append(sessionId, event, { targetPath });
+      relayed += 1;
+    } catch {
+      // Append errors are observable via the stream but should not
+      // abort the rest of the batch — partial relay is still progress.
+    }
+  }
+
+  let persistedCursor = false;
+  if (typeof polled.cursor === "string" && polled.cursor.trim()) {
+    const result = await writeSyncCursor(sessionId, polled.cursor, { targetPath }).catch(() => null);
+    persistedCursor = Boolean(result && result.written);
+  }
+
+  return {
+    ok: true,
+    reason: "",
+    relayed,
+    dropped: Array.isArray(polled.dropped) ? polled.dropped.length : 0,
+    cursor: typeof polled.cursor === "string" ? polled.cursor : startCursor || null,
+    persistedCursor,
+  };
+}

package/src/session/store.js

@@ -484,6 +484,52 @@ export async function listActiveSessions({ targetPath = process.cwd() } = {}) {
   return sessions;
 }
 
+/**
+ * List every session known to the local cache. Unlike
+ * `listActiveSessions`, this includes archived AND expired sessions so
+ * the CLI can surface past conversations the way ChatGPT exposes its
+ * left-rail history.
+ *
+ * Each entry carries `archiveStatus` (`"active"` | `"archived"` |
+ * `"expired"`) so the consumer can group/filter without re-deriving
+ * lifecycle from the raw timestamps.
+ *
+ * @param {{targetPath?: string}} [options]
+ * @returns {Promise<Array<object>>}
+ */
+export async function listAllSessions({ targetPath = process.cwd() } = {}) {
+  const resolvedTargetPath = path.resolve(String(targetPath || "."));
+  const sessionsRoot = resolveSessionsRoot({ targetPath: resolvedTargetPath });
+  let entries = [];
+  try {
+    entries = await fsp.readdir(sessionsRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+
+  const sessions = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const loaded = await loadMetadata(entry.name, { targetPath: resolvedTargetPath });
+    if (!loaded) continue;
+
+    const payload = buildSessionPayload(loaded.metadata, loaded.paths);
+    let archiveStatus = "active";
+    if (loaded.metadata.status === SESSION_STATUS_ARCHIVED) {
+      archiveStatus = "archived";
+    } else if (isExpired(loaded.metadata)) {
+      archiveStatus = "expired";
+    }
+    sessions.push({ ...payload, archiveStatus });
+  }
+
+  sessions.sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+  return sessions;
+}
+
 export async function renewSession(sessionId, { targetPath = process.cwd() } = {}) {
   const loaded = await loadMetadata(sessionId, { targetPath });
   if (!loaded) {

package/src/session/sync-cursor.js

@@ -0,0 +1,62 @@
+/**
+ * Per-session sync cursor persistence.
+ *
+ * The daemon keeps the human-message poll cursor in memory; one-shot CLI
+ * commands (`slc session sync`, `slc session read --remote`) need a
+ * cursor that survives across invocations so successive runs only fetch
+ * what is new. We persist the cursor next to the stream NDJSON in the
+ * session directory.
+ */
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { resolveSessionDir } from "./paths.js";
+
+function cursorPath(sessionId, { targetPath } = {}) {
+  return path.join(resolveSessionDir(sessionId, { targetPath }), "remote-sync-cursor.json");
+}
+
+/**
+ * Read the persisted human-message cursor for a session. Returns `null`
+ * when no cursor has been recorded yet, or when the file is missing,
+ * empty, or malformed — callers should treat that as "first sync".
+ *
+ * @param {string} sessionId
+ * @param {{targetPath?: string}} [options]
+ * @returns {Promise<string|null>}
+ */
+export async function readSyncCursor(sessionId, { targetPath } = {}) {
+  if (!sessionId) return null;
+  const filePath = cursorPath(sessionId, { targetPath });
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const cursor = typeof parsed?.cursor === "string" ? parsed.cursor.trim() : "";
+    return cursor || null;
+  } catch (err) {
+    if (err && err.code === "ENOENT") return null;
+    return null;
+  }
+}
+
+/**
+ * Persist the human-message cursor for a session. No-op when cursor is
+ * empty so we never overwrite a real value with an empty one.
+ *
+ * @param {string} sessionId
+ * @param {string|null|undefined} cursor
+ * @param {{targetPath?: string}} [options]
+ * @returns {Promise<{written: boolean, path: string}>}
+ */
+export async function writeSyncCursor(sessionId, cursor, { targetPath } = {}) {
+  const filePath = cursorPath(sessionId, { targetPath });
+  const normalized = typeof cursor === "string" ? cursor.trim() : "";
+  if (!sessionId || !normalized) {
+    return { written: false, path: filePath };
+  }
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  const payload = { cursor: normalized, updatedAt: new Date().toISOString() };
+  await fsp.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+  return { written: true, path: filePath };
+}