sentinelayer-cli 0.9.4 → 0.9.5

package/package.json

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

package/src/commands/session.js

@@ -68,6 +68,7 @@ import {
 import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
 import { mergeLiveSources } from "../session/live-source.js";
 import { listenSessionEvents } from "../session/listener.js";
+import { buildSessionRecap } from "../session/recap.js";
 import { deriveSessionTitle } from "../session/senti-naming.js";
 import { pushSessionTitleToApi } from "../session/title-sync.js";
 import {
@@ -560,6 +561,51 @@ function formatEventLine(event = {}) {
   return `${ts} ${agentId} ${type}`;
 }
 
+async function appendMissingRemoteEvents(sessionId, remoteEvents = [], { targetPath } = {}) {
+  const events = Array.isArray(remoteEvents) ? remoteEvents : [];
+  if (events.length === 0) {
+    return {
+      appended: 0,
+      skipped: 0,
+      failed: 0,
+    };
+  }
+  const knownKeys = new Set();
+  const localEvents = await readStream(sessionId, {
+    targetPath,
+    tail: 0,
+  });
+  for (const event of localEvents) {
+    addSessionEventIdentityKeys(knownKeys, event);
+  }
+
+  let appended = 0;
+  let skipped = 0;
+  let failed = 0;
+  for (const event of events) {
+    if (sessionEventHasKnownIdentity(event, knownKeys)) {
+      skipped += 1;
+      continue;
+    }
+    try {
+      const persisted = await appendToStream(sessionId, event, {
+        targetPath,
+        syncRemote: false,
+      });
+      addSessionEventIdentityKeys(knownKeys, persisted);
+      appended += 1;
+    } catch {
+      addSessionEventIdentityKeys(knownKeys, event);
+      failed += 1;
+    }
+  }
+  return {
+    appended,
+    skipped,
+    failed,
+  };
+}
+
 function formatTemplateLaunchLine(slot = {}) {
   const terminal = Number(slot.terminal || 0);
   const role = normalizeString(slot.role) || "agent";
@@ -1479,6 +1525,92 @@ export function registerSessionCommand(program) {
       }
     });
 
+  const recap = session
+    .command("recap")
+    .description("Build deterministic Senti session recaps");
+
+  recap
+    .command("now [sessionId]")
+    .description("Summarize current session activity, peers, findings, locks, and task ownership")
+    .option("--session <id>", "Session id to recap")
+    .option(
+      "--remote",
+      "Hydrate the latest durable API events before building the recap",
+    )
+    .option(
+      "--agent <id>",
+      "Agent id requesting the recap; self-authored events are omitted from recent snippets",
+      process.env.SENTINELAYER_AGENT_ID || "",
+    )
+    .option("--max-events <n>", "Maximum recent local events to inspect (default 100)", "100")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId) || resolveSessionIdOption(options);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const agentId = normalizeAgentId(options.agent, "");
+      const maxEvents = parsePositiveInteger(options.maxEvents, "max-events", 100);
+      let hydration = null;
+      let remoteTail = null;
+      let remoteAppend = null;
+      if (options.remote) {
+        hydration = await hydrateSessionFromRemote({
+          sessionId: normalizedSessionId,
+          targetPath,
+        });
+        remoteTail = await pollSessionEventsBefore(normalizedSessionId, {
+          targetPath,
+          limit: maxEvents,
+          timeoutMs: 15_000,
+        });
+        if (remoteTail?.ok && Array.isArray(remoteTail.events) && remoteTail.events.length > 0) {
+          remoteAppend = await appendMissingRemoteEvents(normalizedSessionId, remoteTail.events, {
+            targetPath,
+          });
+        }
+      }
+      const current = await buildSessionRecap(normalizedSessionId, {
+        forAgentId: agentId,
+        maxEvents,
+        targetPath,
+      });
+      const payload = {
+        command: "session recap now",
+        targetPath,
+        sessionId: normalizedSessionId,
+        agentId: current.forAgentId,
+        maxEvents,
+        generatedAt: current.generatedAt,
+        ephemeral: current.ephemeral,
+        style: current.style,
+        recap: current.text,
+        summary: current.summary,
+        remote: options.remote
+          ? {
+              hydration,
+              tailProbe: remoteTail
+                ? {
+                    ok: Boolean(remoteTail.ok),
+                    reason: remoteTail.reason || "",
+                    count: Array.isArray(remoteTail.events) ? remoteTail.events.length : 0,
+                    cursor: remoteTail.cursor || null,
+                  }
+                : null,
+              appendedTail: remoteAppend,
+            }
+          : null,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(pc.bold(`Recap for session ${normalizedSessionId}`));
+      if (payload.agentId) {
+        console.log(pc.gray(`for agent=${payload.agentId}`));
+      }
+      console.log(current.text);
+    });
+
   session
     .command("read <sessionId>")
     .description("Read recent session messages")

package/src/session/recap.js

@@ -3,8 +3,10 @@ import path from "node:path";
 import process from "node:process";
 
 import { createAgentEvent } from "../events/schema.js";
+import { dedupeSessionEvents } from "./event-identity.js";
 import { resolveSessionPaths } from "./paths.js";
 import { appendToStream, readStream } from "./stream.js";
+import { getSession } from "./store.js";
 
 const SENTI_AGENT_ID = "senti";
 const SENTI_MODEL = "gpt-5.4-mini";
@@ -279,11 +281,12 @@ async function readTaskLedgerSummary(
   }
 }
 
-function buildElapsedMinutes(events = [], nowIso = new Date().toISOString()) {
-  if (!Array.isArray(events) || events.length === 0) {
+function elapsedMinutesBetween(startIso, nowIso = new Date().toISOString()) {
+  const normalizedStartIso = normalizeString(startIso);
+  if (!normalizedStartIso) {
     return 0;
   }
-  const firstEpoch = toEpoch(events[0]?.ts, nowIso);
+  const firstEpoch = toEpoch(normalizedStartIso, nowIso);
   const nowEpoch = toEpoch(nowIso, nowIso);
   if (!Number.isFinite(firstEpoch) || !Number.isFinite(nowEpoch) || nowEpoch <= firstEpoch) {
     return 0;
@@ -291,6 +294,51 @@ function buildElapsedMinutes(events = [], nowIso = new Date().toISOString()) {
   return Math.max(0, Math.floor((nowEpoch - firstEpoch) / 60_000));
 }
 
+function earliestIso(values = [], fallbackIso = new Date().toISOString()) {
+  const validEpochs = values
+    .map((value) => normalizeString(value))
+    .filter(Boolean)
+    .map((value) => Date.parse(value))
+    .filter((value) => Number.isFinite(value));
+  if (validEpochs.length === 0) {
+    return "";
+  }
+  validEpochs.sort((left, right) => left - right);
+  return normalizeIsoTimestamp(new Date(validEpochs[0]).toISOString(), fallbackIso);
+}
+
+function buildElapsedMinutes(events = [], nowIso = new Date().toISOString(), { startedAt = "" } = {}) {
+  const eventStart = Array.isArray(events) && events.length > 0 ? events[0]?.ts || events[0]?.timestamp : "";
+  const startIso = earliestIso([startedAt, eventStart], nowIso);
+  return elapsedMinutesBetween(startIso, nowIso);
+}
+
+function eventSequenceNumber(event = {}) {
+  for (const value of [event.sequenceId, event.sequence, event.seq, event.payload?.sequenceId]) {
+    const normalized = Number(value);
+    if (Number.isFinite(normalized)) {
+      return normalized;
+    }
+  }
+  return 0;
+}
+
+function sortEventsByConversationTime(events = [], fallbackIso = new Date().toISOString()) {
+  return [...(Array.isArray(events) ? events : [])].sort((left, right) => {
+    const leftEpoch = toEpoch(left?.ts || left?.timestamp, fallbackIso);
+    const rightEpoch = toEpoch(right?.ts || right?.timestamp, fallbackIso);
+    if (leftEpoch !== rightEpoch) {
+      return leftEpoch - rightEpoch;
+    }
+    const leftSequence = eventSequenceNumber(left);
+    const rightSequence = eventSequenceNumber(right);
+    if (leftSequence !== rightSequence) {
+      return leftSequence - rightSequence;
+    }
+    return normalizeString(left?.cursor).localeCompare(normalizeString(right?.cursor));
+  });
+}
+
 function buildRecapKey(sessionId, targetPath) {
   return `${path.resolve(String(targetPath || "."))}::${normalizeString(sessionId)}`;
 }
@@ -413,10 +461,19 @@ export async function buildSessionRecap(
   const normalizedMaxEvents = normalizePositiveInteger(maxEvents, DEFAULT_RECAP_MAX_EVENTS);
   const normalizedForAgentId = normalizeString(forAgentId);
 
-  const events = await readStream(normalizedSessionId, {
+  const allEvents = await readStream(normalizedSessionId, {
     targetPath: normalizedTargetPath,
-    tail: normalizedMaxEvents,
+    tail: 0,
   });
+  let sessionMetadata = null;
+  try {
+    sessionMetadata = await getSession(normalizedSessionId, { targetPath: normalizedTargetPath });
+  } catch {
+    sessionMetadata = null;
+  }
+  const events = sortEventsByConversationTime(dedupeSessionEvents(allEvents), normalizedNow).slice(
+    -normalizedMaxEvents,
+  );
   const visibleEvents = (Array.isArray(events) ? events : []).filter((event) => {
     const agentId = normalizeString(event.agent?.id || event.agentId);
     if (!agentId) {
@@ -452,7 +509,10 @@ export async function buildSessionRecap(
     forAgentId: normalizedForAgentId,
     limit: 2,
   });
-  const elapsedMinutes = buildElapsedMinutes(visibleEvents, normalizedNow);
+  const windowElapsedMinutes = buildElapsedMinutes(visibleEvents, normalizedNow);
+  const elapsedMinutes = buildElapsedMinutes(visibleEvents, normalizedNow, {
+    startedAt: sessionMetadata?.createdAt,
+  });
   const latestEvent = visibleEvents.length > 0 ? visibleEvents[visibleEvents.length - 1] : null;
   const recapText = buildRecapText({
     activeAgents,
@@ -481,6 +541,10 @@ export async function buildSessionRecap(
       taskLedger,
       snippets,
       elapsedMinutes,
+      windowElapsedMinutes,
+      sessionStartedAt: sessionMetadata?.createdAt
+        ? normalizeIsoTimestamp(sessionMetadata.createdAt, normalizedNow)
+        : null,
       lastActorId: normalizeString(latestEvent?.agent?.id || latestEvent?.agentId) || null,
       lastEventAt: latestEvent ? normalizeIsoTimestamp(latestEvent.ts, normalizedNow) : null,
     },