sentinelayer-cli 0.9.3 → 0.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.9.3",
+  "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";
@@ -13,6 +15,14 @@ const DEFAULT_RECAP_MAX_EVENTS = 100;
 const DEFAULT_RECAP_INTERVAL_MS = 300_000;
 const DEFAULT_RECAP_INACTIVITY_MS = 600_000;
 const DEFAULT_RECAP_ACTIVITY_THRESHOLD = 5;
+const DEFAULT_TASK_SUMMARY_LIMIT = 3;
+const ACTIVE_TASK_STATUSES = new Set(["PENDING", "ACCEPTED", "BLOCKED"]);
+const TASK_STATUS_KEYS = {
+  PENDING: "pending",
+  ACCEPTED: "accepted",
+  COMPLETED: "completed",
+  BLOCKED: "blocked",
+};
 
 const ACTIVE_RECAP_EMITTERS = new Map();
 
@@ -160,11 +170,123 @@ async function readPendingTasks(sessionId, { forAgentId = "", targetPath = proce
   }
 }
 
-function buildElapsedMinutes(events = [], nowIso = new Date().toISOString()) {
-  if (!Array.isArray(events) || events.length === 0) {
+function normalizeTaskStatus(value) {
+  const normalized = normalizeString(value).toUpperCase();
+  return Object.prototype.hasOwnProperty.call(TASK_STATUS_KEYS, normalized)
+    ? normalized
+    : "PENDING";
+}
+
+function taskOwner(task = {}) {
+  return (
+    normalizeString(task.toAgentId) ||
+    normalizeString(task.requestedToAgentId) ||
+    (normalizeString(task.roleFilter) ? `role:${normalizeString(task.roleFilter)}` : "") ||
+    "unassigned"
+  );
+}
+
+function shortTaskText(value) {
+  const text = normalizeString(value).replace(/\s+/g, " ");
+  if (text.length <= 80) {
+    return text;
+  }
+  return `${text.slice(0, 77)}...`;
+}
+
+function emptyTaskLedgerSummary() {
+  return {
+    total: 0,
+    active: 0,
+    pending: 0,
+    accepted: 0,
+    blocked: 0,
+    completed: 0,
+    owners: [],
+    recent: [],
+  };
+}
+
+function summarizeTaskLedger(tasks = [], { limit = DEFAULT_TASK_SUMMARY_LIMIT } = {}) {
+  const summary = emptyTaskLedgerSummary();
+  const owners = new Map();
+  const normalizedTasks = [];
+
+  for (const task of Array.isArray(tasks) ? tasks : []) {
+    if (!task || typeof task !== "object") {
+      continue;
+    }
+    const status = normalizeTaskStatus(task.status);
+    const statusKey = TASK_STATUS_KEYS[status];
+    const owner = taskOwner(task);
+    const priority = normalizeString(task.priority) || "when-free";
+    const taskId = normalizeString(task.taskId) || "task";
+    const updatedAt = normalizeIsoTimestamp(
+      task.updatedAt || task.completedAt || task.acceptedAt || task.createdAt,
+      new Date().toISOString(),
+    );
+    const record = {
+      taskId,
+      status,
+      priority,
+      owner,
+      task: shortTaskText(task.task),
+      updatedAt,
+    };
+    normalizedTasks.push(record);
+    summary.total += 1;
+    summary[statusKey] += 1;
+
+    if (ACTIVE_TASK_STATUSES.has(status)) {
+      summary.active += 1;
+      const ownerRecord = owners.get(owner) || {
+        agentId: owner,
+        active: 0,
+        pending: 0,
+        accepted: 0,
+        blocked: 0,
+      };
+      ownerRecord.active += 1;
+      ownerRecord[statusKey] += 1;
+      owners.set(owner, ownerRecord);
+    }
+  }
+
+  summary.owners = [...owners.values()]
+    .sort((left, right) => {
+      if (right.active !== left.active) return right.active - left.active;
+      return left.agentId.localeCompare(right.agentId);
+    })
+    .slice(0, Math.max(1, limit));
+  summary.recent = normalizedTasks
+    .sort((left, right) => toEpoch(right.updatedAt) - toEpoch(left.updatedAt))
+    .slice(0, Math.max(1, limit));
+  return summary;
+}
+
+async function readTaskLedgerSummary(
+  sessionId,
+  { targetPath = process.cwd(), limit = DEFAULT_TASK_SUMMARY_LIMIT } = {},
+) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  try {
+    const raw = await fsp.readFile(paths.tasksPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return summarizeTaskLedger(parsed?.tasks || [], { limit });
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return emptyTaskLedgerSummary();
+    }
+    return emptyTaskLedgerSummary();
+  }
+}
+
+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;
@@ -172,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)}`;
 }
@@ -181,6 +348,7 @@ function buildRecapText({
   totalFindings = 0,
   activeLocks = 0,
   pendingTasks = 0,
+  taskLedger = emptyTaskLedgerSummary(),
   snippets = [],
 } = {}) {
   const agentText =
@@ -191,13 +359,49 @@ function buildRecapText({
   const lockText = `${activeLocks} file lock${activeLocks === 1 ? "" : "s"} active`;
   const pendingText =
     pendingTasks > 0 ? `You have ${pendingTasks} pending task${pendingTasks === 1 ? "" : "s"}.` : "";
+  const taskText = buildTaskLedgerText(taskLedger);
   const snippetText = snippets.length > 0 ? `Recent: ${snippets.join(" | ")}` : "";
-  return `While you were away: ${agentText}. ${findingText}. ${lockText}. ${pendingText} ${snippetText}`.replace(
+  return `While you were away: ${agentText}. ${findingText}. ${lockText}. ${pendingText} ${taskText}. ${snippetText}`.replace(
     /\s+/g,
     " "
   ).trim();
 }
 
+function buildTaskLedgerText(taskLedger = emptyTaskLedgerSummary()) {
+  const total = Number(taskLedger.total || 0);
+  if (!total) {
+    return "Tasks: none queued";
+  }
+  const active = Number(taskLedger.active || 0);
+  const counts = [
+    `${Number(taskLedger.pending || 0)} pending`,
+    `${Number(taskLedger.accepted || 0)} accepted`,
+    `${Number(taskLedger.blocked || 0)} blocked`,
+    `${Number(taskLedger.completed || 0)} done`,
+  ].join(", ");
+  const ownerText =
+    Array.isArray(taskLedger.owners) && taskLedger.owners.length > 0
+      ? `Owners: ${taskLedger.owners
+          .map((owner) => {
+            const parts = [];
+            if (owner.pending) parts.push(`${owner.pending} pending`);
+            if (owner.accepted) parts.push(`${owner.accepted} accepted`);
+            if (owner.blocked) parts.push(`${owner.blocked} blocked`);
+            return `${owner.agentId} (${parts.join("/") || `${owner.active || 0} active`})`;
+          })
+          .join("; ")}`
+      : "Owners: none active";
+  const recentText =
+    Array.isArray(taskLedger.recent) && taskLedger.recent.length > 0
+      ? `Recent tasks: ${taskLedger.recent
+          .map((task) => `${task.priority} ${task.status} ${task.owner}: ${task.task}`)
+          .join(" | ")}`
+      : "";
+  return [`Tasks: ${active} active of ${total} total (${counts})`, ownerText, recentText]
+    .filter(Boolean)
+    .join(". ");
+}
+
 // Multi-agent session etiquette + read-path rules surfaced in the
 // context_briefing payload an agent receives on first join. Web
 // renders this as markdown (see sentinelayer-web Session.tsx
@@ -235,7 +439,8 @@ function buildPeriodicText(recap = {}) {
   const activeLocks = Number(summary.activeLocks || 0);
   const lastActor = normalizeString(summary.lastActorId);
   const actorText = lastActor ? `${lastActor} active` : "no active actor";
-  return `Session active for ${elapsedMinutes}m. ${activeAgents} agents. ${totalFindings} findings. ${activeLocks} locks. ${actorText}.`;
+  const taskText = buildTaskLedgerText(summary.taskLedger);
+  return `Session active for ${elapsedMinutes}m. ${activeAgents} agents. ${totalFindings} findings. ${activeLocks} locks. ${taskText}. ${actorText}.`;
 }
 
 export async function buildSessionRecap(
@@ -256,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) {
@@ -288,17 +502,24 @@ export async function buildSessionRecap(
     forAgentId: normalizedForAgentId,
     targetPath: normalizedTargetPath,
   });
+  const taskLedger = await readTaskLedgerSummary(normalizedSessionId, {
+    targetPath: normalizedTargetPath,
+  });
   const snippets = summarizeRecentActivity(visibleEvents, {
     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,
     totalFindings: totalFindingsCount,
     activeLocks,
     pendingTasks,
+    taskLedger,
     snippets,
   });
 
@@ -317,8 +538,13 @@ export async function buildSessionRecap(
       totalFindingsCount,
       activeLocks,
       pendingTasksForAgent: pendingTasks,
+      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,
     },