sentinelayer-cli 0.18.1 → 0.19.0

package/package.json

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

package/src/session/daemon.js

@@ -39,8 +39,8 @@ import {
   DEFAULT_RECAP_INTERVAL_MS,
   emitPeriodicRecap,
 } from "./recap.js";
+import { hydrateSessionFromRemote } from "./remote-hydrate.js";
 import { stopRuntimeRunsForSession } from "./runtime-bridge.js";
-import { pollHumanMessages } from "./sync.js";
 import { getSession, renewSession } from "./store.js";
 import { appendToStream, readStream, tailStream } from "./stream.js";
 import { handleTaskDirective } from "./tasks.js";
@@ -214,6 +214,7 @@ function createSentiState({
   checkpointCloseoutOnStop,
   helpResponder,
   llmInvoker,
+  remoteHydrator,
   telemetrySessionId,
 }) {
   return {
@@ -243,6 +244,7 @@ function createSentiState({
     lastCheckpointResult: null,
     helpResponder,
     llmInvoker,
+    remoteHydrator,
     telemetrySessionId,
     running: true,
     tickTimer: null,
@@ -255,6 +257,7 @@ function createSentiState({
     lastTickSummary: null,
     recapEmitter: null,
     humanMessageCursor: null,
+    sessionEventsCursor: null,
     humanMessagePollInFlight: false,
   };
 }
@@ -1055,6 +1058,9 @@ function createHealthSummaryBase(nowIso, session, agents) {
       relayed: 0,
       dropped: 0,
       cursor: null,
+      sessionEventsRelayed: 0,
+      sessionEventsCursor: null,
+      eventsBackfillComplete: null,
       reason: "",
     },
     recap: {
@@ -1236,7 +1242,7 @@ async function maybeRenewActiveSession(
   };
 }
 
-async function pollAndRelayHumanMessages(
+async function hydrateRemoteSessionEvents(
   daemonState,
   summary,
   nowIso = new Date().toISOString()
@@ -1248,37 +1254,44 @@ async function pollAndRelayHumanMessages(
 
   daemonState.humanMessagePollInFlight = true;
   try {
-    const polled = await pollHumanMessages(daemonState.sessionId, {
+    const hydrated = await daemonState.remoteHydrator({
+      sessionId: daemonState.sessionId,
       targetPath: daemonState.targetPath,
-      since: daemonState.humanMessageCursor,
     });
-    if (!polled.ok) {
-      summary.humanMessages.reason = normalizeString(polled.reason) || "poll_failed";
+    if (!hydrated.ok) {
+      summary.humanMessages.reason = normalizeString(hydrated.reason) || "poll_failed";
       summary.humanMessages.cursor = daemonState.humanMessageCursor;
+      summary.humanMessages.sessionEventsCursor = daemonState.sessionEventsCursor;
       return;
     }
 
-    const relayedEvents = [];
-    for (const event of polled.events || []) {
-      const persisted = await appendToStream(daemonState.sessionId, event, {
-        targetPath: daemonState.targetPath,
-      });
-      relayedEvents.push(persisted);
-    }
-    daemonState.humanMessageCursor = normalizeString(polled.cursor) || daemonState.humanMessageCursor;
+    const relayed = Math.max(0, Math.floor(Number(hydrated.relayed || 0)));
+    const humanRelayed = Math.max(0, Math.floor(Number(hydrated.humanRelayed || 0)));
+    const sessionEventsRelayed = Math.max(0, Math.floor(Number(hydrated.eventsRelayed || 0)));
+    daemonState.humanMessageCursor = normalizeString(hydrated.cursor) || daemonState.humanMessageCursor;
+    daemonState.sessionEventsCursor =
+      normalizeString(hydrated.eventsCursor) || daemonState.sessionEventsCursor;
 
-    summary.humanMessages.relayed = relayedEvents.length;
-    summary.humanMessages.dropped = Array.isArray(polled.dropped) ? polled.dropped.length : 0;
+    summary.humanMessages.relayed = relayed;
+    summary.humanMessages.dropped = Math.max(0, Math.floor(Number(hydrated.dropped || 0)));
     summary.humanMessages.cursor = daemonState.humanMessageCursor;
+    summary.humanMessages.sessionEventsRelayed = sessionEventsRelayed;
+    summary.humanMessages.sessionEventsCursor = daemonState.sessionEventsCursor;
+    summary.humanMessages.humanEventsRelayed = humanRelayed;
+    summary.humanMessages.eventsBackfillComplete = Boolean(hydrated.eventsBackfillComplete);
+    summary.humanMessages.eventsPageCount = Math.max(0, Math.floor(Number(hydrated.eventsPageCount || 0)));
+    summary.humanMessages.localAppendComplete = hydrated.localAppendComplete !== false;
     summary.humanMessages.reason = "";
 
-    if (relayedEvents.length > 0) {
+    if (humanRelayed > 0) {
       await emitSentiEvent(
         daemonState.sessionId,
         "daemon_alert",
         {
           alert: "human_directive_received",
-          relayedCount: relayedEvents.length,
+          relayedCount: relayed,
+          humanEventsRelayed: humanRelayed,
+          sessionEventsRelayed,
           droppedCount: summary.humanMessages.dropped,
         },
         {
@@ -1291,6 +1304,7 @@ async function pollAndRelayHumanMessages(
     summary.humanMessages.reason =
       normalizeString(error?.message) || "poll_relay_failed";
     summary.humanMessages.cursor = daemonState.humanMessageCursor;
+    summary.humanMessages.sessionEventsCursor = daemonState.sessionEventsCursor;
   } finally {
     daemonState.humanMessagePollInFlight = false;
   }
@@ -1466,6 +1480,7 @@ export async function runSentiHealthTick(
       checkpointCloseoutOnStop: true,
       helpResponder: null,
       llmInvoker: invokeViaProxy,
+      remoteHydrator: hydrateSessionFromRemote,
       telemetrySessionId: null,
     });
   const normalizedNow = normalizeIsoTimestamp(nowIso, new Date().toISOString());
@@ -1486,7 +1501,7 @@ export async function runSentiHealthTick(
   await emitStaleAndRecoveryAlerts(resolvedDaemonState, summary, staleAgents, normalizedNow);
   await emitConflictAlerts(resolvedDaemonState, summary, filteredAgents, normalizedNow);
   await maybeRenewActiveSession(resolvedDaemonState, summary, session, normalizedNow);
-  await pollAndRelayHumanMessages(resolvedDaemonState, summary, normalizedNow);
+  await hydrateRemoteSessionEvents(resolvedDaemonState, summary, normalizedNow);
   await maybeEmitPeriodicRecap(resolvedDaemonState, summary, normalizedNow);
   await maybeGenerateSessionCheckpoint(resolvedDaemonState, summary, normalizedNow);
   return summary;
@@ -1513,6 +1528,7 @@ export async function startSenti(
     checkpointCloseoutOnStop = true,
     helpResponder = null,
     llmInvoker = invokeViaProxy,
+    remoteHydrator = hydrateSessionFromRemote,
   } = {}
 ) {
   const normalizedSessionId = normalizeString(sessionId);
@@ -1597,6 +1613,7 @@ export async function startSenti(
     checkpointCloseoutOnStop: checkpointCloseoutOnStop !== false,
     helpResponder,
     llmInvoker: typeof llmInvoker === "function" ? llmInvoker : invokeViaProxy,
+    remoteHydrator: typeof remoteHydrator === "function" ? remoteHydrator : hydrateSessionFromRemote,
     telemetrySessionId: telemetrySession?.id || null,
   });
 
@@ -1792,6 +1809,7 @@ export async function startSenti(
       lastCheckpointSourceSequenceId: daemonState.lastCheckpointSourceSequenceId,
       lastCheckpointResult: daemonState.lastCheckpointResult,
       humanMessageCursor: daemonState.humanMessageCursor,
+      sessionEventsCursor: daemonState.sessionEventsCursor,
     }),
   };
 

package/src/session/recap.js

@@ -17,6 +17,9 @@ 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 DEFAULT_WORK_PLAN_SUMMARY_LIMIT = 5;
+const MAX_WORK_PLAN_BYTES = 128_000;
+const WORK_PLAN_RELATIVE_PATH = "tasks/todo.md";
 const RECAP_SOURCE_IGNORED_EVENTS = new Set([
   "agent_heartbeat",
   "agent_join",
@@ -399,6 +402,105 @@ function emptyTaskLedgerSummary() {
   };
 }
 
+function emptyWorkPlanSummary() {
+  return {
+    path: WORK_PLAN_RELATIVE_PATH,
+    exists: false,
+    truncated: false,
+    total: 0,
+    open: 0,
+    completed: 0,
+    currentSection: "",
+    recentOpen: [],
+    recent: [],
+  };
+}
+
+function shortWorkPlanText(value) {
+  const text = normalizeString(value)
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/\s+/g, " ");
+  if (text.length <= 100) {
+    return text;
+  }
+  return `${text.slice(0, 97)}...`;
+}
+
+function summarizeWorkPlanMarkdown(raw = "", { limit = DEFAULT_WORK_PLAN_SUMMARY_LIMIT, truncated = false } = {}) {
+  const summary = emptyWorkPlanSummary();
+  summary.exists = true;
+  summary.truncated = Boolean(truncated);
+
+  const records = [];
+  let section = "";
+  for (const line of String(raw || "").split(/\r?\n/)) {
+    const headingMatch = /^(#{1,4})\s+(.+?)\s*$/.exec(line);
+    if (headingMatch) {
+      section = shortWorkPlanText(headingMatch[2]);
+      continue;
+    }
+
+    const taskMatch = /^\s*[-*]\s+\[([ xX])\]\s+(.+?)\s*$/.exec(line);
+    if (!taskMatch) {
+      continue;
+    }
+    const completed = taskMatch[1].toLowerCase() === "x";
+    const record = {
+      status: completed ? "completed" : "open",
+      section,
+      task: shortWorkPlanText(taskMatch[2]),
+    };
+    if (!record.task) {
+      continue;
+    }
+    records.push(record);
+    summary.total += 1;
+    if (completed) {
+      summary.completed += 1;
+    } else {
+      summary.open += 1;
+    }
+    summary.currentSection = section || summary.currentSection;
+  }
+
+  const normalizedLimit = Math.max(1, normalizePositiveInteger(limit, DEFAULT_WORK_PLAN_SUMMARY_LIMIT));
+  summary.recentOpen = records
+    .filter((record) => record.status === "open")
+    .slice(-normalizedLimit);
+  summary.recent = records.slice(-normalizedLimit);
+  return summary;
+}
+
+async function readWorkPlanSummary({ targetPath = process.cwd(), limit = DEFAULT_WORK_PLAN_SUMMARY_LIMIT } = {}) {
+  const filePath = path.join(path.resolve(String(targetPath || ".")), WORK_PLAN_RELATIVE_PATH);
+  try {
+    const stats = await fsp.stat(filePath);
+    let source = "";
+    let truncated = false;
+    if (stats.size > MAX_WORK_PLAN_BYTES) {
+      truncated = true;
+      const handle = await fsp.open(filePath, "r");
+      try {
+        const buffer = Buffer.alloc(MAX_WORK_PLAN_BYTES);
+        const position = Math.max(0, stats.size - MAX_WORK_PLAN_BYTES);
+        const { bytesRead } = await handle.read(buffer, 0, MAX_WORK_PLAN_BYTES, position);
+        source = buffer.subarray(0, bytesRead).toString("utf-8");
+      } finally {
+        await handle.close();
+      }
+    } else {
+      source = await fsp.readFile(filePath, "utf-8");
+    }
+    return summarizeWorkPlanMarkdown(source, { limit, truncated });
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return emptyWorkPlanSummary();
+    }
+    return emptyWorkPlanSummary();
+  }
+}
+
 function summarizeTaskLedger(tasks = [], { limit = DEFAULT_TASK_SUMMARY_LIMIT } = {}) {
   const summary = emptyTaskLedgerSummary();
   const owners = new Map();
@@ -541,6 +643,7 @@ function buildRecapText({
   activeLocks = 0,
   pendingTasks = 0,
   taskLedger = emptyTaskLedgerSummary(),
+  workPlan = emptyWorkPlanSummary(),
   usageSummary = normalizeUsageSummary(),
   snippets = [],
 } = {}) {
@@ -554,8 +657,9 @@ function buildRecapText({
     pendingTasks > 0 ? `You have ${pendingTasks} pending task${pendingTasks === 1 ? "" : "s"}.` : "";
   const taskText = buildTaskLedgerText(taskLedger);
   const usageText = buildUsageLedgerText(usageSummary);
+  const workPlanText = buildWorkPlanText(workPlan);
   const snippetText = snippets.length > 0 ? `Recent: ${snippets.join(" | ")}` : "";
-  return `While you were away: ${agentText}. ${findingText}. ${lockText}. ${pendingText} ${taskText}. ${usageText} ${snippetText}`.replace(
+  return `While you were away: ${agentText}. ${findingText}. ${lockText}. ${pendingText} ${taskText}. ${workPlanText} ${usageText} ${snippetText}`.replace(
     /\s+/g,
     " "
   ).trim();
@@ -596,6 +700,31 @@ function buildTaskLedgerText(taskLedger = emptyTaskLedgerSummary()) {
     .join(". ");
 }
 
+function buildWorkPlanText(workPlan = emptyWorkPlanSummary()) {
+  if (!workPlan || typeof workPlan !== "object" || !workPlan.exists) {
+    return "";
+  }
+  const open = Number(workPlan.open || 0);
+  const completed = Number(workPlan.completed || 0);
+  const pathText = normalizeString(workPlan.path) || WORK_PLAN_RELATIVE_PATH;
+  const currentSection = normalizeString(workPlan.currentSection);
+  const currentText = currentSection ? ` Current: ${currentSection}.` : "";
+  const recentOpen = Array.isArray(workPlan.recentOpen) ? workPlan.recentOpen : [];
+  const nextText =
+    recentOpen.length > 0
+      ? ` Next: ${recentOpen
+          .map((item) => {
+            const section = normalizeString(item.section);
+            const task = normalizeString(item.task);
+            return section ? `${section} - ${task}` : task;
+          })
+          .filter(Boolean)
+          .join("; ")}.`
+      : "";
+  const truncatedText = workPlan.truncated ? " Recent window only." : "";
+  return `Plan: ${open} open / ${completed} done in ${pathText}.${currentText}${nextText}${truncatedText}`;
+}
+
 function roundCurrency(value) {
   const normalized = Number(value || 0);
   if (!Number.isFinite(normalized) || normalized < 0) {
@@ -702,11 +831,12 @@ function buildPeriodicText(recap = {}) {
   const lastActor = normalizeString(summary.lastActorId);
   const actorText = lastActor ? `${lastActor} active` : "no active actor";
   const taskText = buildTaskLedgerText(summary.taskLedger);
+  const workPlanText = buildWorkPlanText(summary.workPlan);
   const usageText = buildUsageLedgerText({
     totals: summary.usageTotals,
     topAgents: summary.usageTopAgents,
   });
-  return `Session active for ${elapsedMinutes}m. ${activeAgents} agents. ${totalFindings} findings. ${activeLocks} locks. ${taskText}. ${usageText} ${actorText}.`.replace(
+  return `Session active for ${elapsedMinutes}m. ${activeAgents} agents. ${totalFindings} findings. ${activeLocks} locks. ${taskText}. ${workPlanText} ${usageText} ${actorText}.`.replace(
     /\s+/g,
     " ",
   ).trim();
@@ -774,6 +904,9 @@ export async function buildSessionRecap(
   const taskLedger = await readTaskLedgerSummary(normalizedSessionId, {
     targetPath: normalizedTargetPath,
   });
+  const workPlan = await readWorkPlanSummary({
+    targetPath: normalizedTargetPath,
+  });
   const snippets = summarizeRecentActivity(visibleEvents, {
     forAgentId: normalizedForAgentId,
     limit: 2,
@@ -789,6 +922,7 @@ export async function buildSessionRecap(
     activeLocks,
     pendingTasks,
     taskLedger,
+    workPlan,
     usageSummary,
     snippets,
   });
@@ -809,6 +943,7 @@ export async function buildSessionRecap(
       activeLocks,
       pendingTasksForAgent: pendingTasks,
       taskLedger,
+      workPlan,
       usageTotals: usageSummary.totals,
       usageTopAgents: usageSummary.topAgents,
       snippets,

package/src/session/sync.js

@@ -243,6 +243,23 @@ function eventSequenceNumber(event = {}) {
   return 0;
 }
 
+function nextBeforeSequenceFromPayload(payload = {}, events = []) {
+  const explicit = Number(payload?.next_before_sequence ?? payload?.nextBeforeSequence);
+  if (Number.isFinite(explicit) && explicit > 0) {
+    return Math.floor(explicit);
+  }
+
+  let minimumSequence = 0;
+  for (const event of Array.isArray(events) ? events : []) {
+    const sequence = eventSequenceNumber(event);
+    if (sequence <= 0) continue;
+    if (minimumSequence === 0 || sequence < minimumSequence) {
+      minimumSequence = sequence;
+    }
+  }
+  return minimumSequence || null;
+}
+
 function chronologicalSessionEvents(events = []) {
   return (Array.isArray(events) ? events : [])
     .map((event, index) => ({ event, index }))
@@ -1219,13 +1236,12 @@ export async function pollSessionEventsBefore(
 
     const events = chronologicalSessionEvents(payload?.events || []);
     const lastEvent = events[events.length - 1] || null;
-    const firstEvent = events[0] || null;
     return {
       ok: true,
       reason: "",
       events,
       cursor: normalizeString(lastEvent?.cursor) || null,
-      beforeSequence: eventSequenceNumber(firstEvent) || null,
+      beforeSequence: nextBeforeSequenceFromPayload(payload, payload?.events || []),
     };
   } catch (error) {
     recordCircuitFailure(inboundCircuit, normalizedNowMs);