sentinelayer-cli 0.19.0 → 0.21.0

package/src/session/listener.js

@@ -1,6 +1,6 @@
 import { setTimeout as delay } from "node:timers/promises";
 
-import { pollSessionEvents } from "./sync.js";
+import { pollSessionEvents, pollSessionEventsBefore, streamSessionEvents } from "./sync.js";
 import { cursorAdvances, readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
 
 const BROADCAST_RECIPIENTS = new Set([
@@ -199,6 +199,21 @@ function humanActivityTimestampMs(event = {}, nowMs = Date.now()) {
   return eventTimestampMs(event) || nowMs;
 }
 
+function eventTimeRange(events = []) {
+  let oldestMs = 0;
+  let newestMs = 0;
+  for (const event of Array.isArray(events) ? events : []) {
+    const timeMs = eventTimestampMs(event);
+    if (!timeMs) continue;
+    if (!oldestMs || timeMs < oldestMs) oldestMs = timeMs;
+    if (!newestMs || timeMs > newestMs) newestMs = timeMs;
+  }
+  return {
+    oldestEventAt: oldestMs ? new Date(oldestMs).toISOString() : null,
+    newestEventAt: newestMs ? new Date(newestMs).toISOString() : null,
+  };
+}
+
 function isRecentActivity(activityMs, nowMs, windowMs) {
   return (
     Number.isFinite(activityMs) &&
@@ -208,6 +223,14 @@ function isRecentActivity(activityMs, nowMs, windowMs) {
   );
 }
 
+function isListenerLifecycleEvent(event = {}) {
+  if (!isPlainObject(event)) return false;
+  const payload = isPlainObject(event.payload) ? event.payload : {};
+  const eventType = normalizeString(event.event || event.type).toLowerCase();
+  if (eventType.startsWith("session_listener_")) return true;
+  return normalizeString(payload.source).toLowerCase() === "session_listen";
+}
+
 /**
  * Poll session events in the background and emit only events addressed to
  * the current agent or broadcast to everyone. The loop advances its cursor
@@ -224,11 +247,18 @@ export async function listenSessionEvents({
   limit = 200,
   since = undefined,
   replay = false,
+  fromNow = false,
+  persistStartCursor = false,
   maxPolls = null,
   signal,
   onEvent = async () => {},
   onError = async () => {},
+  onCatchup = async () => {},
+  onLifecycle = async () => {},
+  transport = "poll",
   _poll = pollSessionEvents,
+  _pollLatest = pollSessionEventsBefore,
+  _stream = streamSessionEvents,
   _readCursor = readSyncCursor,
   _writeCursor = writeSyncCursor,
   _sleep = defaultSleep,
@@ -240,17 +270,32 @@ export async function listenSessionEvents({
     throw new Error("session id is required.");
   }
 
+  if (fromNow && since !== undefined) {
+    throw new Error("Use either fromNow or since, not both.");
+  }
+  const normalizedTransport = normalizeLower(transport) || "poll";
+  if (!["auto", "poll", "stream"].includes(normalizedTransport)) {
+    throw new Error("transport must be one of: auto, poll, stream.");
+  }
+
   const cursorSuffix = listenCursorSuffix(normalizedAgentId);
-  let cursor =
-    typeof since === "string" || since === null
-      ? normalizeString(since) || null
-      : await _readCursor(normalizedSessionId, { targetPath, suffix: cursorSuffix });
+  const explicitSince = typeof since === "string" || since === null;
+  let cursor = explicitSince
+    ? normalizeString(since) || null
+    : await _readCursor(normalizedSessionId, { targetPath, suffix: cursorSuffix });
+  let cursorSource = explicitSince ? "explicit" : cursor ? "stored" : "none";
   let primed = Boolean(cursor) || Boolean(replay);
   let pollCount = 0;
   let emitted = 0;
   let matched = 0;
   let persistedCursor = false;
   let lastReason = "";
+  let activeTransport = normalizedTransport === "poll" ? "poll" : "stream";
+  let streamAttempted = false;
+  let streamFallbackReason = "";
+  let catchupNotified = false;
+  let catchupEventCount = 0;
+  let catchupMatchingEventCount = 0;
   const emittedKeys = new Set();
   const maxPollCount = normalizePositiveInteger(maxPolls, 0);
   const pollLimit = normalizePositiveInteger(limit, 200);
@@ -261,82 +306,264 @@ export async function listenSessionEvents({
   const activeWindowMs =
     Math.max(1, normalizePositiveInteger(activeWindowSeconds, DEFAULT_ACTIVE_WINDOW_SECONDS)) *
     1000;
+
+  if (fromNow) {
+    const latest = await _pollLatest(normalizedSessionId, {
+      targetPath,
+      limit: 1,
+    });
+    if (!latest?.ok) {
+      throw new Error(`Unable to start listener from the latest event (${latest?.reason || "unknown"}).`);
+    }
+    cursor = normalizeString(latest.cursor) || null;
+    cursorSource = cursor ? "from_now" : "none";
+    primed = Boolean(cursor) || Boolean(replay);
+    if (cursor && persistStartCursor) {
+      const writeResult = await _writeCursor(normalizedSessionId, cursor, {
+        targetPath,
+        suffix: cursorSuffix,
+      }).catch(() => null);
+      persistedCursor = Boolean(writeResult?.written) || persistedCursor;
+    }
+  }
+
   const startedAtMs = Number(_nowMs()) || Date.now();
   let lastHumanActivityMs = 0;
   let lastSleepMs = 0;
 
-  while (!signal?.aborted) {
-    pollCount += 1;
-    const result = await _poll(normalizedSessionId, {
-      targetPath,
-      since: cursor,
-      limit: pollLimit,
-    });
+  const lifecycleSnapshot = (type, extra = {}) => ({
+    type,
+    sessionId: normalizedSessionId,
+    agentId: normalizedAgentId,
+    cursor: cursor || null,
+    cursorSuffix,
+    pollCount,
+    matched,
+    emitted,
+    persistedCursor,
+    cursorSource,
+    transport: activeTransport,
+    idleIntervalSeconds: Math.round(idleSleepMs / 1000),
+    activeIntervalSeconds: Math.round(activeSleepMs / 1000),
+    activeWindowSeconds: Math.round(activeWindowMs / 1000),
+    lastHumanActivityAt: lastHumanActivityMs
+      ? new Date(lastHumanActivityMs).toISOString()
+      : null,
+    lastSleepMs,
+    reason: lastReason,
+    ...extra,
+  });
 
-    if (result?.ok) {
-      lastReason = "";
-      const events = Array.isArray(result.events) ? result.events : [];
-      const nextCursor = normalizeString(result.cursor) || cursorFromEvents(events, cursor);
-      const cursorDidNotAdvance = Boolean(nextCursor && cursor && !cursorAdvances(nextCursor, cursor));
-      const cursorFault = cursorDidNotAdvance && (nextCursor !== cursor || events.length > 0);
-      if (cursorFault) {
-        lastReason = "cursor_not_advanced";
-        await onError({
-          ok: false,
-          reason: lastReason,
-          cursor: cursor || null,
-          candidateCursor: nextCursor,
-        });
-      } else {
-        const observedAtMs = Number(_nowMs()) || Date.now();
-        for (const event of events) {
-          const activityMs = humanActivityTimestampMs(event, observedAtMs);
-          if (isRecentActivity(activityMs, observedAtMs, activeWindowMs)) {
-            lastHumanActivityMs = Math.max(lastHumanActivityMs, activityMs);
-          }
-        }
-        const shouldEmitBatch = primed || Boolean(replay);
-        for (const event of events) {
-          if (!eventMatchesAgent(event, normalizedAgentId)) continue;
-          const key = eventIdentityKey(event);
-          if (emittedKeys.has(key)) continue;
-          matched += 1;
-          if (!shouldEmitBatch && eventTimestampMs(event) < startedAtMs) continue;
-          await onEvent(event);
-          emittedKeys.add(key);
-          emitted += 1;
-        }
-
-        if (nextCursor && nextCursor !== cursor) {
-          const writeResult = await _writeCursor(normalizedSessionId, nextCursor, {
-            targetPath,
-            suffix: cursorSuffix,
-          }).catch(() => null);
-          persistedCursor = Boolean(writeResult?.written) || persistedCursor;
-          cursor = nextCursor;
-        }
-        primed = true;
-      }
-    } else {
-      lastReason = normalizeString(result?.reason) || "poll_failed";
+  async function notifyCatchup(payload) {
+    try {
+      await onCatchup(payload);
+    } catch (error) {
       await onError({
         ok: false,
-        reason: lastReason,
-        cursor: result?.cursor || cursor || null,
+        reason: "catchup_notice_failed",
+        cursor: payload.cursor || cursor || null,
+        detail: normalizeString(error?.message),
       });
     }
+  }
 
-    if (maxPollCount > 0 && pollCount >= maxPollCount) break;
-    const sleepAtMs = Number(_nowMs()) || Date.now();
-    const humanActive = isRecentActivity(lastHumanActivityMs, sleepAtMs, activeWindowMs);
-    const nextSleepMs = humanActive ? Math.min(idleSleepMs, activeSleepMs) : idleSleepMs;
-    lastSleepMs = nextSleepMs;
+  async function notifyLifecycle(payload) {
     try {
-      await _sleep(nextSleepMs, { signal });
+      await onLifecycle(payload);
     } catch (error) {
-      if (shouldAbort(error, signal)) break;
-      throw error;
+      await onError({
+        ok: false,
+        reason: `lifecycle_${payload.type}_failed`,
+        cursor: payload.cursor || cursor || null,
+        detail: normalizeString(error?.message),
+      });
+    }
+  }
+
+  async function processEventBatch(eventsInput = [], resultCursor = null) {
+    const events = Array.isArray(eventsInput) ? eventsInput : [];
+    const nextCursor = normalizeString(resultCursor) || cursorFromEvents(events, cursor);
+    const cursorDidNotAdvance = Boolean(nextCursor && cursor && !cursorAdvances(nextCursor, cursor));
+    const cursorFault = cursorDidNotAdvance && (nextCursor !== cursor || events.length > 0);
+    if (cursorFault) {
+      lastReason = "cursor_not_advanced";
+      await onError({
+        ok: false,
+        reason: lastReason,
+        cursor: cursor || null,
+        candidateCursor: nextCursor,
+      });
+      return false;
+    }
+
+    const observedAtMs = Number(_nowMs()) || Date.now();
+    const visibleEvents = [];
+    let preStartEventCount = 0;
+    for (const event of events) {
+      const timestampMs = eventTimestampMs(event);
+      if (!timestampMs || timestampMs < startedAtMs) {
+        preStartEventCount += 1;
+      }
+      const activityMs = humanActivityTimestampMs(event, observedAtMs);
+      if (isRecentActivity(activityMs, observedAtMs, activeWindowMs)) {
+        lastHumanActivityMs = Math.max(lastHumanActivityMs, activityMs);
+      }
+      if (isListenerLifecycleEvent(event)) continue;
+      if (!eventMatchesAgent(event, normalizedAgentId)) continue;
+      visibleEvents.push(event);
+    }
+
+    if (
+      !catchupNotified &&
+      cursorSource === "stored" &&
+      Boolean(cursor) &&
+      events.length > 0 &&
+      preStartEventCount > 0
+    ) {
+      catchupNotified = true;
+      catchupEventCount = events.length;
+      catchupMatchingEventCount = visibleEvents.length;
+      await notifyCatchup({
+        type: "catchup",
+        sessionId: normalizedSessionId,
+        agentId: normalizedAgentId,
+        cursor: cursor || null,
+        candidateCursor: nextCursor || null,
+        cursorSuffix,
+        cursorSource,
+        pollCount,
+        eventCount: events.length,
+        matchingEventCount: visibleEvents.length,
+        preStartEventCount,
+        limit: pollLimit,
+        replay: Boolean(replay),
+        ...eventTimeRange(events),
+      });
+    }
+
+    const shouldEmitBatch = primed || Boolean(replay);
+    for (const event of visibleEvents) {
+      const key = eventIdentityKey(event);
+      if (emittedKeys.has(key)) continue;
+      matched += 1;
+      if (!shouldEmitBatch && eventTimestampMs(event) < startedAtMs) continue;
+      await onEvent(event);
+      emittedKeys.add(key);
+      emitted += 1;
+    }
+
+    if (nextCursor && nextCursor !== cursor) {
+      const writeResult = await _writeCursor(normalizedSessionId, nextCursor, {
+        targetPath,
+        suffix: cursorSuffix,
+      }).catch(() => null);
+      persistedCursor = Boolean(writeResult?.written) || persistedCursor;
+      cursor = nextCursor;
+    }
+    primed = true;
+    return true;
+  }
+
+  async function notifyHeartbeat({ stopping = false, nextPollMs = null } = {}) {
+    const heartbeatAtMs = Number(_nowMs()) || Date.now();
+    const humanActive = isRecentActivity(lastHumanActivityMs, heartbeatAtMs, activeWindowMs);
+    await notifyLifecycle(
+      lifecycleSnapshot("heartbeat", {
+        active: humanActive,
+        state: humanActive ? "active" : "idle",
+        nextPollMs,
+        stopping,
+        transport: activeTransport,
+      }),
+    );
+    return humanActive;
+  }
+
+  await notifyLifecycle(
+    lifecycleSnapshot("started", {
+      startedAt: new Date(startedAtMs).toISOString(),
+      transport: activeTransport,
+    }),
+  );
+
+  try {
+    if (normalizedTransport !== "poll") {
+      streamAttempted = true;
+      activeTransport = "stream";
+      const streamResult = await _stream(normalizedSessionId, {
+        targetPath,
+        since: cursor,
+        signal,
+        onEvent: async (event) => {
+          await processEventBatch([event], normalizeString(event?.cursor) || cursor);
+        },
+        onError: async (error) => {
+          lastReason = `stream_${normalizeString(error?.reason) || "error"}`;
+          await onError({
+            ok: false,
+            reason: lastReason,
+            cursor: error?.cursor || cursor || null,
+          });
+        },
+        onHeartbeat: async () => {
+          await notifyHeartbeat({ nextPollMs: null });
+        },
+      });
+      if (!streamResult?.ok) {
+        streamFallbackReason = normalizeString(streamResult?.reason) || lastReason || "stream_failed";
+        lastReason = `stream_${streamFallbackReason}`;
+      } else if (!signal?.aborted) {
+        streamFallbackReason = "stream_closed";
+      }
+    }
+
+    const shouldPoll =
+      !signal?.aborted && (normalizedTransport === "poll" || normalizedTransport === "auto");
+    if (shouldPoll) {
+      activeTransport = "poll";
+    }
+    while (shouldPoll && !signal?.aborted) {
+      pollCount += 1;
+      const result = await _poll(normalizedSessionId, {
+        targetPath,
+        since: cursor,
+        limit: pollLimit,
+      });
+
+      if (result?.ok) {
+        lastReason = "";
+        await processEventBatch(result.events, result.cursor);
+      } else {
+        lastReason = normalizeString(result?.reason) || "poll_failed";
+        await onError({
+          ok: false,
+          reason: lastReason,
+          cursor: result?.cursor || cursor || null,
+        });
+      }
+
+      const willStop = maxPollCount > 0 && pollCount >= maxPollCount;
+      const heartbeatAtMs = Number(_nowMs()) || Date.now();
+      const humanActive = isRecentActivity(lastHumanActivityMs, heartbeatAtMs, activeWindowMs);
+      const nextSleepMs = humanActive ? Math.min(idleSleepMs, activeSleepMs) : idleSleepMs;
+      await notifyHeartbeat({ nextPollMs: willStop ? null : nextSleepMs, stopping: willStop });
+
+      if (willStop) break;
+      lastSleepMs = nextSleepMs;
+      try {
+        await _sleep(nextSleepMs, { signal });
+      } catch (error) {
+        if (shouldAbort(error, signal)) break;
+        throw error;
+      }
     }
+  } finally {
+    await notifyLifecycle(
+      lifecycleSnapshot("stopped", {
+        stoppedAt: new Date(Number(_nowMs()) || Date.now()).toISOString(),
+        aborted: Boolean(signal?.aborted),
+      }),
+    );
   }
 
   return {
@@ -345,10 +572,17 @@ export async function listenSessionEvents({
     agentId: normalizedAgentId,
     cursor,
     cursorSuffix,
+    cursorSource,
+    transport: activeTransport,
+    streamAttempted,
+    streamFallbackReason,
     pollCount,
     matched,
     emitted,
     persistedCursor,
+    catchupNotified,
+    catchupEventCount,
+    catchupMatchingEventCount,
     idleIntervalSeconds: Math.round(idleSleepMs / 1000),
     activeIntervalSeconds: Math.round(activeSleepMs / 1000),
     activeWindowSeconds: Math.round(activeWindowMs / 1000),

package/src/session/pricing-ledger.js

@@ -14,6 +14,30 @@ const SUPPORTED_SESSION_USAGE_SCHEMAS = new Set([
   LOCAL_SESSION_USAGE_SCHEMA,
   ...LEGACY_SESSION_USAGE_SCHEMAS,
 ]);
+const USAGE_HINT_KEYS = [
+  "totalTokens",
+  "total_tokens",
+  "tokens",
+  "tokenTotal",
+  "token_total",
+  "inputTokens",
+  "input_tokens",
+  "tokensIn",
+  "tokens_in",
+  "promptTokens",
+  "prompt_tokens",
+  "outputTokens",
+  "output_tokens",
+  "tokensOut",
+  "tokens_out",
+  "completionTokens",
+  "completion_tokens",
+  "providerCostUsd",
+  "provider_cost_usd",
+  "costUsd",
+  "cost_usd",
+  "cost",
+];
 
 function n(value) {
   return String(value == null ? "" : value).trim();
@@ -53,6 +77,11 @@ function pickText(sources, keys) {
   return n(pick(sources, keys));
 }
 
+function hasUsageHints(value) {
+  const bag = object(value);
+  return USAGE_HINT_KEYS.some((key) => bag[key] != null && bag[key] !== "");
+}
+
 function pickInt(sources, keys) {
   return nonNegativeInt(pick(sources, keys)) ?? 0;
 }
@@ -109,13 +138,14 @@ export function buildUsageLedgerEntry(
   { sessionId = "", priceBookVersion = DEFAULT_PRICE_BOOK_VERSION, billingTier = "unknown" } = {},
 ) {
   const kind = n(event?.event || event?.type);
-  if (kind !== SESSION_USAGE_EVENT) return null;
-
   const payload = object(event?.payload);
   const schema = n(payload.schema);
-  if (!SUPPORTED_SESSION_USAGE_SCHEMAS.has(schema)) return null;
-
   const usage = object(payload.usage);
+  const legacyUsageEvent = kind !== SESSION_USAGE_EVENT && hasUsageHints(usage);
+  if (!legacyUsageEvent) {
+    if (kind !== SESSION_USAGE_EVENT) return null;
+    if (!SUPPORTED_SESSION_USAGE_SCHEMAS.has(schema)) return null;
+  }
   const prompt = object(payload.prompt);
   const response = object(payload.response);
   const agent = object(event?.agent);

package/src/session/recap.js

@@ -801,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.",
   "",