sentinelayer-cli 0.9.0 → 0.9.3

package/src/session/remote-hydrate.js

@@ -18,11 +18,188 @@
  * sync, and vice-versa.
  */
 
-import { pollHumanMessages, pollSessionEvents } from "./sync.js";
-import { appendToStream } from "./stream.js";
+import { listSessionsFromApi, pollHumanMessages, pollSessionEvents } from "./sync.js";
+import { appendToStream, readStream } from "./stream.js";
+import {
+  createSession,
+  getSession,
+  isSessionCacheExpired,
+  refreshSessionCacheForRemoteActivity,
+} from "./store.js";
 import { readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
+import {
+  addSessionEventIdentityKeys,
+  sessionEventHasKnownIdentity,
+} from "./event-identity.js";
 
 const EVENTS_CURSOR_SUFFIX = "events";
+const DEFAULT_EVENT_PAGE_LIMIT = 200;
+const DEFAULT_MAX_EVENT_PAGES = 25;
+
+async function readExistingRelayKeys(sessionId, { targetPath = process.cwd() } = {}) {
+  const knownKeys = new Set();
+  const events = await readStream(sessionId, { targetPath, tail: 0 }).catch(() => []);
+  for (const event of events) {
+    addSessionEventIdentityKeys(knownKeys, event);
+  }
+  return knownKeys;
+}
+
+async function ensureLocalSessionShell(sessionId, { targetPath = process.cwd() } = {}) {
+  const existing = await getSession(sessionId, { targetPath });
+  let remoteStatus = "";
+  let remoteSession = null;
+  const remoteList = await listSessionsFromApi({
+    targetPath,
+    includeArchived: true,
+    limit: 200,
+  }).catch(() => null);
+  if (remoteList?.ok) {
+    const match = (remoteList.sessions || []).find((entry) => entry?.sessionId === sessionId);
+    remoteSession = match || null;
+    remoteStatus = String(match?.archiveStatus || match?.status || "").trim().toLowerCase();
+  }
+  if (existing) {
+    const existingStatus = String(existing.status || "").trim().toLowerCase();
+    const locallyClosedByStatus = existingStatus === "expired" || existingStatus === "archived";
+    const remoteAllowsRefresh =
+      ["active", "pending"].includes(remoteStatus) || (!remoteStatus && !locallyClosedByStatus);
+    if (isSessionCacheExpired(existing) && remoteAllowsRefresh) {
+      const refreshed = await refreshSessionCacheForRemoteActivity(sessionId, {
+        targetPath,
+        title: remoteSession?.title || "",
+        lastInteractionAt:
+          remoteSession?.lastInteractionAt ||
+          remoteSession?.lastActivityAt ||
+          remoteSession?.updatedAt ||
+          remoteSession?.createdAt ||
+          "",
+      });
+      return {
+        materialized: false,
+        refreshed: Boolean(refreshed),
+        session: refreshed || existing,
+        remoteStatus,
+      };
+    }
+    return { materialized: false, refreshed: false, session: existing, remoteStatus };
+  }
+  const created = await createSession({
+    targetPath,
+    sessionId,
+    title: `remote-${String(sessionId).slice(0, 8)}`,
+  });
+  return { materialized: true, refreshed: false, session: created, remoteStatus };
+}
+
+function sourceFullyRelayed(events = [], successfulKeys = new Set()) {
+  const relayedEvents = Array.isArray(events) ? events : [];
+  if (relayedEvents.length === 0) return true;
+  return relayedEvents.every((event) => sessionEventHasKnownIdentity(event, successfulKeys));
+}
+
+function markPostKillEvent(event = {}) {
+  if (!event || typeof event !== "object" || Array.isArray(event)) return event;
+  const payload = event.payload && typeof event.payload === "object" && !Array.isArray(event.payload)
+    ? event.payload
+    : {};
+  return {
+    ...event,
+    _post_kill: true,
+    payload: {
+      ...payload,
+      _post_kill: true,
+    },
+  };
+}
+
+function normalizePositiveInteger(value, fallbackValue) {
+  if (value === undefined || value === null || String(value).trim() === "") {
+    return fallbackValue;
+  }
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    return fallbackValue;
+  }
+  return Math.floor(normalized);
+}
+
+async function pollSessionEventPages({
+  sessionId,
+  targetPath,
+  since,
+  _pollEvents,
+  limit,
+  maxPages,
+  forceCircuitProbe = false,
+}) {
+  const normalizedLimit = Math.max(
+    1,
+    Math.min(DEFAULT_EVENT_PAGE_LIMIT, normalizePositiveInteger(limit, DEFAULT_EVENT_PAGE_LIMIT)),
+  );
+  const normalizedMaxPages = Math.max(
+    1,
+    Math.min(100, normalizePositiveInteger(maxPages, DEFAULT_MAX_EVENT_PAGES)),
+  );
+  const events = [];
+  let cursor = typeof since === "string" && since.trim() ? since.trim() : null;
+  let reason = "";
+  let pageCount = 0;
+
+  for (let page = 0; page < normalizedMaxPages; page += 1) {
+    const result = await _pollEvents(sessionId, {
+      targetPath,
+      since: cursor,
+      limit: normalizedLimit,
+      forceCircuitProbe,
+    });
+    pageCount += 1;
+    if (!result?.ok) {
+      return {
+        ok: events.length > 0,
+        reason: result?.reason || "poll_failed",
+        events,
+        cursor,
+        pageCount,
+        complete: false,
+        truncated: events.length > 0,
+      };
+    }
+
+    const pageEvents = Array.isArray(result.events) ? result.events : [];
+    events.push(...pageEvents);
+    const nextCursor =
+      typeof result.cursor === "string" && result.cursor.trim() ? result.cursor.trim() : cursor;
+    const progressed = nextCursor && nextCursor !== cursor;
+    cursor = nextCursor || cursor;
+
+    if (pageEvents.length < normalizedLimit) {
+      return {
+        ok: true,
+        reason: "",
+        events,
+        cursor,
+        pageCount,
+        complete: true,
+        truncated: false,
+      };
+    }
+    if (!progressed) {
+      reason = "cursor_not_advanced";
+      break;
+    }
+  }
+
+  return {
+    ok: events.length > 0,
+    reason: reason || "max_event_pages_reached",
+    events,
+    cursor,
+    pageCount,
+    complete: false,
+    truncated: true,
+  };
+}
 
 /**
  * Fetch new human messages for a session, append them to the local
@@ -46,6 +223,10 @@ export async function hydrateSessionFromRemote({
   _poll = pollHumanMessages,
   _pollEvents = pollSessionEvents,
   _append = appendToStream,
+  _ensureLocalSession = ensureLocalSessionShell,
+  probeOpenCircuit = true,
+  eventPageLimit = DEFAULT_EVENT_PAGE_LIMIT,
+  maxEventPages = DEFAULT_MAX_EVENT_PAGES,
 } = {}) {
   if (!sessionId || typeof sessionId !== "string") {
     return {
@@ -74,25 +255,56 @@ export async function hydrateSessionFromRemote({
   // Run both pollers in parallel — they hit different endpoints and
   // are independent. A human-only poll stays fast even when the
   // events poll is heavy.
-  const [humanResult, eventsResult] = await Promise.all([
+  let [humanResult, eventsResult] = await Promise.all([
     _poll(sessionId, { targetPath, since: humanCursor }),
-    _pollEvents(sessionId, { targetPath, since: eventsCursor }),
+    pollSessionEventPages({
+      sessionId,
+      targetPath,
+      since: eventsCursor,
+      _pollEvents,
+      limit: eventPageLimit,
+      maxPages: maxEventPages,
+    }),
   ]);
 
+  if (
+    probeOpenCircuit &&
+    humanResult?.reason === "circuit_breaker_open" &&
+    eventsResult?.reason === "circuit_breaker_open"
+  ) {
+    [humanResult, eventsResult] = await Promise.all([
+      _poll(sessionId, { targetPath, since: humanCursor, forceCircuitProbe: true }),
+      pollSessionEventPages({
+        sessionId,
+        targetPath,
+        since: eventsCursor,
+        _pollEvents,
+        limit: eventPageLimit,
+        maxPages: maxEventPages,
+        forceCircuitProbe: true,
+      }),
+    ]);
+  }
+
   // Dedup across sources — both endpoints can return the same event
   // (e.g. a human relay event). Cursor values are unique per event.
   const seenCursors = new Set();
+  const seenKeys = new Set();
   const merged = [];
   for (const e of humanResult?.events || []) {
     const c = (e && typeof e === "object" && typeof e.cursor === "string") ? e.cursor : "";
     if (c && seenCursors.has(c)) continue;
+    if (sessionEventHasKnownIdentity(e, seenKeys)) continue;
     if (c) seenCursors.add(c);
+    addSessionEventIdentityKeys(seenKeys, e);
     merged.push(e);
   }
   for (const e of eventsResult?.events || []) {
     const c = (e && typeof e === "object" && typeof e.cursor === "string") ? e.cursor : "";
     if (c && seenCursors.has(c)) continue;
+    if (sessionEventHasKnownIdentity(e, seenKeys)) continue;
     if (c) seenCursors.add(c);
+    addSessionEventIdentityKeys(seenKeys, e);
     merged.push(e);
   }
 
@@ -112,10 +324,33 @@ export async function hydrateSessionFromRemote({
   }
 
   let relayed = 0;
-  for (const event of merged) {
+  let materializedLocalSession = false;
+  let remoteStatus = "";
+  const successfulRelayKeys =
+    merged.length > 0 ? await readExistingRelayKeys(sessionId, { targetPath }) : new Set();
+  const newEvents = successfulRelayKeys.size > 0
+    ? merged.filter((event) => !sessionEventHasKnownIdentity(event, successfulRelayKeys))
+    : merged;
+  if (newEvents.length > 0) {
+    try {
+      const localSession = await _ensureLocalSession(sessionId, { targetPath });
+      materializedLocalSession = Boolean(localSession?.materialized);
+      remoteStatus = String(localSession?.remoteStatus || "").trim().toLowerCase();
+    } catch {
+      // Keep the old degraded behavior: append attempts below will
+      // fail visibly in the returned counters, but remote polling still
+      // returns a structured result.
+    }
+  }
+  const appendEvents =
+    remoteStatus && !["active", "pending"].includes(remoteStatus)
+      ? newEvents.map((event) => markPostKillEvent(event))
+      : newEvents;
+  for (const event of appendEvents) {
     try {
-      await _append(sessionId, event, { targetPath });
+      await _append(sessionId, event, { targetPath, syncRemote: false });
       relayed += 1;
+      addSessionEventIdentityKeys(successfulRelayKeys, event);
     } catch {
       // Append errors are observable via the stream but should not
       // abort the rest of the batch — partial relay is still progress.
@@ -123,11 +358,13 @@ export async function hydrateSessionFromRemote({
   }
 
   let persistedCursor = false;
-  if (typeof humanResult?.cursor === "string" && humanResult.cursor.trim()) {
+  const humanCursorSafe = sourceFullyRelayed(humanResult?.events || [], successfulRelayKeys);
+  const eventsCursorSafe = sourceFullyRelayed(eventsResult?.events || [], successfulRelayKeys);
+  if (humanCursorSafe && typeof humanResult?.cursor === "string" && humanResult.cursor.trim()) {
     const result = await writeSyncCursor(sessionId, humanResult.cursor, { targetPath }).catch(() => null);
     persistedCursor = Boolean(result && result.written);
   }
-  if (typeof eventsResult?.cursor === "string" && eventsResult.cursor.trim()) {
+  if (eventsCursorSafe && typeof eventsResult?.cursor === "string" && eventsResult.cursor.trim()) {
     await writeSyncCursor(sessionId, eventsResult.cursor, {
       targetPath,
       suffix: EVENTS_CURSOR_SUFFIX,
@@ -145,5 +382,12 @@ export async function hydrateSessionFromRemote({
     eventsRelayed: (eventsResult?.events || []).length,
     eventsCursor:
       typeof eventsResult?.cursor === "string" ? eventsResult.cursor : eventsCursor || null,
+    eventsPageCount: Number(eventsResult?.pageCount || 0),
+    eventsBackfillComplete: Boolean(eventsResult?.complete !== false),
+    eventsBackfillTruncated: Boolean(eventsResult?.truncated),
+    eventsBackfillReason: eventsResult?.complete === false ? eventsResult?.reason || "" : "",
+    materializedLocalSession,
+    localAppendComplete: humanCursorSafe && eventsCursorSafe,
+    remoteStatus: remoteStatus || null,
   };
 }

package/src/session/store.js

@@ -183,6 +183,31 @@ function normalizeSharedResources(raw = {}, { nowIso = new Date().toISOString()
   };
 }
 
+function normalizeRemoteTitleSync(raw = {}, { nowIso = new Date().toISOString() } = {}) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return null;
+  }
+  const title = normalizeString(raw.title);
+  const lastAttemptAt = raw.lastAttemptAt
+    ? normalizeIsoTimestamp(raw.lastAttemptAt, nowIso)
+    : null;
+  const lastSyncedAt = raw.lastSyncedAt
+    ? normalizeIsoTimestamp(raw.lastSyncedAt, nowIso)
+    : null;
+  const failureReason = normalizeString(raw.failureReason) || null;
+  const pending = Boolean(raw.pending);
+  if (!pending && !title && !lastAttemptAt && !lastSyncedAt && !failureReason) {
+    return null;
+  }
+  return {
+    pending,
+    title: title || null,
+    lastAttemptAt,
+    lastSyncedAt,
+    failureReason,
+  };
+}
+
 function normalizeTemplateAgent(raw = {}) {
   const source = raw && typeof raw === "object" ? raw : {};
   return {
@@ -357,12 +382,14 @@ function normalizeMetadata(raw = {}, { sessionId, targetPath, nowIso } = {}) {
     archiveStatus: normalizeString(raw.archiveStatus) || "pending",
     codebaseContext: normalizeCodebaseContext(raw.codebaseContext || {}),
     sharedResources: normalizeSharedResources(raw.sharedResources || {}, { nowIso }),
+    remoteTitleSync: normalizeRemoteTitleSync(raw.remoteTitleSync || null, { nowIso }),
     template: normalizeSessionTemplate(raw.template || null),
   };
 }
 
 function isExpired(metadata, nowIso = new Date().toISOString()) {
-  if (!metadata || normalizeSessionStatus(metadata.status) === SESSION_STATUS_EXPIRED) {
+  const status = normalizeSessionStatus(metadata?.status);
+  if (!metadata || status === SESSION_STATUS_EXPIRED || status === SESSION_STATUS_ARCHIVED) {
     return true;
   }
   const expiryEpoch = Date.parse(normalizeIsoTimestamp(metadata.expiresAt, nowIso));
@@ -373,6 +400,10 @@ function isExpired(metadata, nowIso = new Date().toISOString()) {
   return nowEpoch >= expiryEpoch;
 }
 
+export function isSessionCacheExpired(metadata, nowIso = new Date().toISOString()) {
+  return isExpired(metadata, nowIso);
+}
+
 function buildSessionPayload(metadata, paths, nowIso = new Date().toISOString()) {
   return {
     sessionId: metadata.sessionId,
@@ -391,6 +422,7 @@ function buildSessionPayload(metadata, paths, nowIso = new Date().toISOString())
     s3Path: metadata.s3Path,
     codebaseContext: metadata.codebaseContext,
     sharedResources: metadata.sharedResources,
+    remoteTitleSync: metadata.remoteTitleSync,
     template: metadata.template,
   };
 }
@@ -464,6 +496,7 @@ export async function createSession({
       archiveStatus: "pending",
       codebaseContext,
       sharedResources: normalizeSharedResources({}, { nowIso }),
+      remoteTitleSync: null,
       template: normalizeSessionTemplate(template),
     },
     {
@@ -498,6 +531,88 @@ export async function updateSessionTitle(
   return buildSessionPayload(saved, loaded.paths, nowIso);
 }
 
+export async function refreshSessionCacheForRemoteActivity(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    title = "",
+    ttlSeconds = DEFAULT_TTL_SECONDS,
+    lastInteractionAt = "",
+    nowIso = new Date().toISOString(),
+  } = {}
+) {
+  const loaded = await loadMetadata(sessionId, { targetPath });
+  if (!loaded) {
+    return null;
+  }
+  const normalizedTtlSeconds = normalizePositiveInteger(ttlSeconds, DEFAULT_TTL_SECONDS);
+  const remoteInteractionIso = normalizeIsoTimestamp(
+    lastInteractionAt,
+    loaded.metadata.lastInteractionAt || loaded.metadata.createdAt || nowIso
+  );
+  const currentInteractionEpoch = Date.parse(
+    normalizeIsoTimestamp(loaded.metadata.lastInteractionAt, loaded.metadata.createdAt || nowIso)
+  );
+  const remoteInteractionEpoch = Date.parse(remoteInteractionIso);
+  const lastInteractionIso =
+    Number.isFinite(remoteInteractionEpoch) &&
+    (!Number.isFinite(currentInteractionEpoch) || remoteInteractionEpoch > currentInteractionEpoch)
+      ? remoteInteractionIso
+      : normalizeIsoTimestamp(loaded.metadata.lastInteractionAt, nowIso);
+
+  const metadata = {
+    ...loaded.metadata,
+    updatedAt: nowIso,
+    expiresAt: toIsoAfterSeconds(nowIso, normalizedTtlSeconds),
+    ttlSeconds: normalizedTtlSeconds,
+    status: SESSION_STATUS_ACTIVE,
+    expiredAt: null,
+    lastInteractionAt: lastInteractionIso,
+  };
+  const normalizedTitle = normalizeString(title);
+  if (normalizedTitle) {
+    metadata.title = normalizedTitle;
+  }
+
+  const saved = await saveMetadata(metadata, loaded.paths);
+  return buildSessionPayload(saved, loaded.paths, nowIso);
+}
+
+export async function recordSessionRemoteTitleSync(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    title = "",
+    pending = false,
+    failureReason = "",
+    lastAttemptAt = "",
+    lastSyncedAt = "",
+  } = {}
+) {
+  const loaded = await loadMetadata(sessionId, { targetPath });
+  if (!loaded) {
+    return null;
+  }
+  const nowIso = new Date().toISOString();
+  const metadata = {
+    ...loaded.metadata,
+    remoteTitleSync: normalizeRemoteTitleSync(
+      {
+        pending: Boolean(pending),
+        title: normalizeString(title) || normalizeString(loaded.metadata.title) || null,
+        lastAttemptAt: lastAttemptAt || nowIso,
+        lastSyncedAt:
+          !pending && !normalizeString(failureReason) ? lastSyncedAt || nowIso : lastSyncedAt || null,
+        failureReason: normalizeString(failureReason) || null,
+      },
+      { nowIso },
+    ),
+    updatedAt: nowIso,
+  };
+  const saved = await saveMetadata(metadata, loaded.paths);
+  return buildSessionPayload(saved, loaded.paths, nowIso);
+}
+
 export async function getSession(sessionId, { targetPath = process.cwd() } = {}) {
   const loaded = await loadMetadata(sessionId, { targetPath });
   if (!loaded) {

package/src/session/stream.js

@@ -3,6 +3,7 @@ import process from "node:process";
 import { setTimeout as sleep } from "node:timers/promises";
 
 import { createAgentEvent, normalizeAgentEvent } from "../events/schema.js";
+import { enrichEventWithMentions } from "./mentions.js";
 import { resolveSessionPaths } from "./paths.js";
 import { redactEventPayload } from "./redact.js";
 import { syncSessionEventToApi } from "./sync.js";
@@ -223,7 +224,7 @@ function filterBySince(events = [], since) {
 export async function appendToStream(
   sessionId,
   event,
-  { targetPath = process.cwd(), maxEvents = DEFAULT_MAX_STREAM_EVENTS } = {}
+  { targetPath = process.cwd(), maxEvents = DEFAULT_MAX_STREAM_EVENTS, syncRemote = true } = {}
 ) {
   const paths = resolveSessionPaths(sessionId, { targetPath });
   const metadata = await readSessionMetadata(paths);
@@ -235,7 +236,14 @@ export async function appendToStream(
   }
 
   const rawEvent = materializeCanonicalEvent(paths.sessionId, event);
-  const canonicalEvent = redactEventPayload(rawEvent);
+  // Parse `@<name>` mentions out of the message text and surface them
+  // as payload.to + payload.mentions so the listener (sl session listen)
+  // and Senti daemon can route to/notify the addressed agent. Pure +
+  // idempotent — if the caller already supplied an explicit `to/recipient`
+  // we leave it alone. Runs before redaction so the redactor sees a
+  // stable shape.
+  const enrichedEvent = enrichEventWithMentions(rawEvent);
+  const canonicalEvent = redactEventPayload(enrichedEvent);
   const nowIso = new Date().toISOString();
   const normalizedMaxEvents = normalizePositiveInteger(maxEvents, DEFAULT_MAX_STREAM_EVENTS);
 
@@ -252,10 +260,12 @@ export async function appendToStream(
     await releaseLock(paths.lockPath);
   }
 
-  // Best-effort dashboard sync. Never block local stream durability on API state.
-  void syncSessionEventToApi(paths.sessionId, canonicalEvent, {
-    targetPath,
-  }).catch(() => {});
+  if (syncRemote) {
+    // Best-effort dashboard sync. Never block local stream durability on API state.
+    void syncSessionEventToApi(paths.sessionId, canonicalEvent, {
+      targetPath,
+    }).catch(() => {});
+  }
 
   return canonicalEvent;
 }
@@ -320,7 +330,7 @@ export async function* tailStream(
     }
 
     try {
-      await sleep(normalizedPollMs, null, signal ? { signal } : undefined);
+      await sleep(normalizedPollMs, null, signal ? { signal, ref: false } : { ref: false });
     } catch (error) {
       if (error && typeof error === "object" && error.name === "AbortError") {
         return;