sentinelayer-cli 0.18.2 → 0.20.0

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) {
@@ -672,11 +801,13 @@ const AGENT_JOIN_RULES = [
   "",
   "**Reading the room** — When you join, the recap above summarizes activity since the last quiet stretch. To read further back, run `sl session read --remote --tail 50 --json` (bump `--tail` if you need more). Do this BEFORE responding so you don't repeat questions or miss a lock-and-claim someone else already opened.",
   "",
-  "**Polling cadence** — Poll new events at most once per 60s (`sl session listen` or `sl session read --remote --tail N`). More frequent than that wastes budget and can hit per-user rate limits. Less frequent than ~5min and peers may think you went idle.",
+  "**Polling cadence** — Poll new events at most once per 60s (`sl session listen` or `sl session read --remote --tail N`). `session listen` is only a delivery cursor, not a grounding command; join or recap before acting. More frequent than that wastes budget and can hit per-user rate limits. Less frequent than ~5min and peers may think you went idle.",
+  "",
+  "**Session grounding** — Long-lived rooms should have one visible daemon owner running `sl session daemon --session <id> --recap-interval 300 --checkpoint-interval 60`. If no durable `session_recap` or `session_checkpoint` is appearing, run `sl session recap now <id> --remote --agent <your-name> --json` before posting a long plan.",
   "",
   "**Writing back** — You can use **markdown**: bold, italic, lists, fenced code, and `inline code`. The web dashboard renders it. Plain text also works. Keep posts terse and technical — link to the work, don't recap it.",
   "",
-  "**Actions and threading** — ACK, view, react, or claim work with message actions instead of top-level chatter: `sl session react <id> ack --target-sequence <n>`, `sl session view <id> <sequence>`, or `sl session action <id> working_on --target-sequence <n>`. Reply to a specific message with `sl session reply <id> <sequence> \"<message>\"`, `sl session comment <id> <sequence> \"<message>\"`, or `sl session say <id> \"<message>\" --reply-to <sequence>`; only start a new top-level post for a new topic. Run `sl session actions` for the full list.",
+  "**Actions and threading** — Use message actions instead of top-level ACK chatter: `sl session react <id> ack --target-sequence <n>` only when an explicit ACK matters, and `sl session action <id> working_on --target-sequence <n>` for ownership. Read receipts are automatic when you run `sl session read <id> --remote --agent <your-name>`; reserve `sl session view <id> <sequence>` for repair/backfill. Reply to a specific message with `sl session reply <id> <sequence> \"<message>\"`, `sl session comment <id> <sequence> \"<message>\"`, or `sl session say <id> \"<message>\" --reply-to <sequence>`; only start a new top-level post for a new topic. Run `sl session actions` for the full list.",
   "",
   "**Search before asking** — Use `sl session search <id> \"<topic>\" --limit 10` to recover old context before asking another agent to re-paste or summarize what is already in the transcript.",
   "",
@@ -702,11 +833,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 +906,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 +924,7 @@ export async function buildSessionRecap(
     activeLocks,
     pendingTasks,
     taskLedger,
+    workPlan,
     usageSummary,
     snippets,
   });
@@ -809,6 +945,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 }))
@@ -411,6 +428,95 @@ async function fetchWithTimeout(url, options, timeoutMs) {
   }
 }
 
+function isAbortLike(error) {
+  return Boolean(error?.name === "AbortError" || error?.code === "ABORT_ERR");
+}
+
+async function* readResponseTextChunks(response) {
+  const body = response?.body;
+  if (!body) return;
+
+  if (typeof body.getReader === "function") {
+    const reader = body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) yield value;
+      }
+    } finally {
+      try {
+        reader.releaseLock();
+      } catch {
+        // Best-effort cleanup only.
+      }
+    }
+    return;
+  }
+
+  if (typeof body[Symbol.asyncIterator] === "function") {
+    for await (const chunk of body) {
+      if (chunk) yield chunk;
+    }
+  }
+}
+
+function extractSseErrorReason(parsed) {
+  const error = parsed?.error && typeof parsed.error === "object" ? parsed.error : {};
+  return (
+    normalizeString(error.code) ||
+    normalizeString(error.message) ||
+    normalizeString(error.detail) ||
+    "session_stream_error"
+  );
+}
+
+async function processSseBlock(block, handlers) {
+  const normalizedBlock = normalizeString(block);
+  if (!normalizedBlock) return;
+
+  const dataLines = [];
+  let commentOnly = true;
+  for (const rawLine of String(block).split("\n")) {
+    const line = rawLine.trimEnd();
+    if (!line) continue;
+    if (line.startsWith(":")) continue;
+    commentOnly = false;
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice(5).trimStart());
+    }
+  }
+
+  if (dataLines.length === 0) {
+    if (commentOnly && typeof handlers.onHeartbeat === "function") {
+      await handlers.onHeartbeat();
+    }
+    return;
+  }
+
+  const rawData = dataLines.join("\n").trim();
+  if (!rawData) return;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(rawData);
+  } catch {
+    await handlers.onError?.({ reason: "malformed_stream_event", cursor: handlers.cursor() });
+    return;
+  }
+
+  if (parsed?.type === "error") {
+    await handlers.onError?.({
+      reason: extractSseErrorReason(parsed),
+      cursor: handlers.cursor(),
+      error: parsed.error || null,
+    });
+    return;
+  }
+
+  await handlers.onEvent?.(parsed);
+}
+
 function sanitizeHumanMessage(rawMessage) {
   const stripped = String(rawMessage || "")
     .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "")
@@ -1114,6 +1220,195 @@ export async function pollSessionEvents(
   }
 }
 
+/**
+ * Consume the API's durable session SSE stream.
+ *
+ * This is the wakeup-first companion to `pollSessionEvents`: the stream uses
+ * Redis wakeups server-side, while the listener can still fall back to durable
+ * `/events` polling if the stream is unavailable or closes.
+ *
+ * @param {string} sessionId
+ * @param {object} [options]
+ * @param {string|null} [options.since] - durable cursor to resume after
+ * @param {AbortSignal} [options.signal]
+ * @param {(event: object) => Promise<void>|void} [options.onEvent]
+ * @param {(payload: object) => Promise<void>|void} [options.onError]
+ * @param {() => Promise<void>|void} [options.onHeartbeat]
+ * @returns {Promise<{ok: boolean, reason: string, cursor: string|null, eventCount: number, errorCount: number, status?: number, aborted?: boolean}>}
+ */
+export async function streamSessionEvents(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    since = null,
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    signal = undefined,
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetch,
+    onEvent = async () => {},
+    onError = async () => {},
+    onHeartbeat = async () => {},
+  } = {}
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedSince = normalizeString(since) || null;
+  if (!normalizedSessionId) {
+    return {
+      ok: false,
+      reason: "invalid_session_id",
+      cursor: normalizedSince,
+      eventCount: 0,
+      errorCount: 0,
+    };
+  }
+
+  let session = null;
+  try {
+    session = await resolveAuthSession({
+      cwd: targetPath,
+      env: process.env,
+      autoRotate: false,
+    });
+  } catch {
+    return {
+      ok: false,
+      reason: "no_session",
+      cursor: normalizedSince,
+      eventCount: 0,
+      errorCount: 0,
+    };
+  }
+  if (!session || !session.token) {
+    return {
+      ok: false,
+      reason: "not_authenticated",
+      cursor: normalizedSince,
+      eventCount: 0,
+      errorCount: 0,
+    };
+  }
+
+  const apiBaseUrl = resolveApiBaseUrl(session);
+  const query = new URLSearchParams();
+  if (normalizedSince) {
+    query.set("after", normalizedSince);
+  }
+  const suffix = query.toString() ? `?${query.toString()}` : "";
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/stream${suffix}`;
+  const controller = new AbortController();
+  const normalizedTimeoutMs = normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS);
+  const timeoutHandle = setTimeout(() => controller.abort(), normalizedTimeoutMs);
+  if (typeof timeoutHandle.unref === "function") {
+    timeoutHandle.unref();
+  }
+  const forwardAbort = () => controller.abort(signal?.reason);
+  if (signal) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+    } else {
+      signal.addEventListener("abort", forwardAbort, { once: true });
+    }
+  }
+
+  let response;
+  try {
+    response = await fetchImpl(
+      endpoint,
+      {
+        method: "GET",
+        headers: {
+          Accept: "text/event-stream",
+          Authorization: `Bearer ${session.token}`,
+        },
+        signal: controller.signal,
+      },
+      normalizedTimeoutMs
+    );
+  } catch (error) {
+    clearTimeout(timeoutHandle);
+    if (signal) signal.removeEventListener("abort", forwardAbort);
+    return {
+      ok: false,
+      reason: isAbortLike(error) || signal?.aborted ? "aborted" : normalizeString(error?.message) || "stream_failed",
+      cursor: normalizedSince,
+      eventCount: 0,
+      errorCount: 0,
+      aborted: Boolean(signal?.aborted || isAbortLike(error)),
+    };
+  }
+  clearTimeout(timeoutHandle);
+
+  let cursor = normalizedSince;
+  let eventCount = 0;
+  let errorCount = 0;
+  let lastErrorReason = "";
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  const handlers = {
+    cursor: () => cursor,
+    onHeartbeat,
+    onError: async (payload) => {
+      errorCount += 1;
+      lastErrorReason = normalizeString(payload?.reason) || "session_stream_error";
+      await onError(payload);
+    },
+    onEvent: async (event) => {
+      const eventCursor = normalizeString(event?.cursor);
+      if (eventCursor) cursor = eventCursor;
+      eventCount += 1;
+      await onEvent(event);
+    },
+  };
+
+  try {
+    if (!response || !response.ok || !response.body) {
+      return {
+        ok: false,
+        reason: `api_${response ? response.status : "no_response"}`,
+        cursor,
+        eventCount,
+        errorCount,
+        status: response?.status,
+      };
+    }
+
+    for await (const chunk of readResponseTextChunks(response)) {
+      buffer += decoder.decode(chunk, { stream: true });
+      buffer = buffer.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+      const blocks = buffer.split("\n\n");
+      buffer = blocks.pop() || "";
+      for (const block of blocks) {
+        await processSseBlock(block, handlers);
+      }
+    }
+    buffer += decoder.decode();
+    if (normalizeString(buffer)) {
+      await processSseBlock(buffer, handlers);
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      reason: isAbortLike(error) || signal?.aborted ? "aborted" : normalizeString(error?.message) || "stream_failed",
+      cursor,
+      eventCount,
+      errorCount,
+      aborted: Boolean(signal?.aborted || isAbortLike(error)),
+    };
+  } finally {
+    if (signal) signal.removeEventListener("abort", forwardAbort);
+  }
+
+  return {
+    ok: !lastErrorReason,
+    reason: lastErrorReason,
+    cursor,
+    eventCount,
+    errorCount,
+    aborted: Boolean(signal?.aborted),
+  };
+}
+
 /**
  * Poll the latest durable session events page via the reverse-history endpoint.
  *
@@ -1219,13 +1514,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);